06: Care to Comment?

[Nuttzy99]

Care to Comment?

Comments play a very important in both the phpBB source and in MOD scripts. Including documentation to explain what is going on will help users understand your code. EMC as much as possible attempts to accomodate the practice of documenting work with comments.

The least you need to know:

• Comment as much as you want in both the phpBB source and the MOD script
• comments in the MOD script can't breakup the command target (ie. the lines to FIND)
• For FINDs, it's helpful to include the original phpBB source line
• Inserting comments containing duplicate text of original phpBB source breaks FIND
• Any text (including duplicate code) will be ignored between /*-MOD and MOD-*/

[/b]
Documenting MOD scripts
The more you can communicate to users trying to (manually) install your MOD the better. Comments in the MOD script are proceeded by a #. When including a comment, you should keep in mind that information between the last # of the command definition and the first # found thereafter limits the target of the command. For example...

Code: Select all

# you can put a comment anywhere in here
#
# you can put a comment anywhere in here
#-------[ FIND ]----------------------------------
# you can put a comment anywhere in here
#
# you can put a comment anywhere in here
#

1st line to find
2nd line to find
# WARNING :: WARNING :: WARNING putting a comment here will
#   cause the 3rd and 4th lines to not be included in the FIND
3rd line to find
4th line to find

# you can put a comment here, now that you intend nothing else
#   to be included in the FIND block

#
#-------[ next command ]-----------------------

...pay close attention to the WARNING. Hitting that comment signals the end of the FIND block. Comments in a MOD script must either be in the same group of # lines in the comment declaration or follow the complete target lines of the command.

There are several things you could leave in comments to help the user install the MOD. For instance when for IN-LINE commands it may be helpful to explain in the script what the resulting line will look like. Probably the most important thing to comment is the FIND command. Since with EMC you will only be stating fragements of lines, it will be very helpful to include in a comment exactly how the full line appears in the original phpBB source.


Inserting Comments into the phpBB source
When writing code to be inserted into PHP or TPL files, it is encouraged that you document your code as much as possible. Every Author has their own style and it is not my intent to tell anyone how their comments should look or when to use them. So again, just to emphasize, commenting the code that will be inserted into PHP and TPL files is encouraged.

However there is one practice that must be denied. Inserting comments into the code that contains duplicate (or near duplicate) text of original phpBB source cannot be allowed. For example if the original phpBB source line looks like this...

Code: Select all

$x = $y + $z ;

...and change the line in some way (any way), for example...

Code: Select all

$x = $y + $z + $foo ;

...you must not insert a descriptive comment that explains what the original line looked like...

Code: Select all

// the original line was:
//$x = $y + $z ;
$x = $y + $z + $foo ;

I understand why a comment like this would be helpful. Unfortunately, this practice cannot be allowed because it is not compatiable with the FIND command. If another MOD needs to FIND the line, it will instead FIND your comment and perform the operations on the commented line instead of the desired line. Unfortunately there is no acceptable way of getting around this. The matter has been discussed at length.


An alternate solution
The EasyMOD program inserts bits of duplicate code into the source so that the uninstall feature may work. A convention is used so that EM will know to skip this block of code. Therefore, you may insert whatever comments you like, including duplicate code, if you use the EM convention. For PHP files, EM will skip any content between /*-MOD and MOD-*/ and all lines between these comments. Content on the same line as these markers will still be valid as long as the content lies outside of it. For TPL files, a similar convention is used: <!--MOD and MOD--> and lines with these markers operate in the same manner as the markers in the PHP files.

-Nuttzy

[smithy_dll]

I'd prefer (if for nothing else but neatness), that comments do not appear on the line before or after the actual action name. This is because I think that the whole block is important in defining the action, and putting runaway text within the lines of the definition could cause problems.

so I would rather say

Code: Select all

# you can put a comment anywhere in here
# you can put a comment anywhere in here
# you can NOT put a comment anywhere in here
#-------[ FIND ]----------------------------------
# you can NOT put a comment anywhere in here
# you can put a comment anywhere in here
# you can put a comment anywhere in here
#

This preserving the official definition of an action, and separating the comment from the action, allowing for a much more human and machine readable format.

[Bananeweizen]

I'd prefer (if for nothing else but neatness), that comments do not appear on the line before or after the actual action name.

I second that vote. All the MODs that I would classify as having a proper and nice readable format do use comments starting at the 4th line of the action like this:

Code: Select all

#
# --------[ ACTION ]----------
#
# comment

Ciao, Michael.

[Nuttzy99]

The MOD Team is free to impose any style restrictions they see fit. So long as it is not incompatiable with EM then there is no problem. In this case, the added restriction the MOD Team might choose to enforce will still work with EM. Its up to the Validators to reject MODs for more stringent restrictions if they want.

As I've said, EM is not a validation tool. I will not be adding code to cripple various style issues. I'm open to making footnotes for cases where the MOD Team has additional restrictions.

-Nuttzy

[-=ET=-]

For FINDs, it's helpful to include the original phpBB source line

I think this summary line may be a little more explained...

Indeed, we all agree (except Ptirhiik perhaps) that FIND on part of code lines are an obligation if we want MOD installations to succeed in the maximum of cases.

But I think we can easily all agree too that even if it's an obligation to do like this, it can be a "bit" confusing for newbies in manual installation to have to find lines with sometimes a very little part of the code which has not really the same look as the whole lines.

So, I think it's the good place here to explain a bit more this suggest like what you've already said there, with this example:

Code: Select all

# 
#-----[ FIND ]------------------------------------------ 
#
# NOTE: the original text is like:
#   $sql = "UPDATE " . USERS_TABLE . "
#      SET " . $username_sql . $passwd_sql . "user_email  ... [ follow by much more ]
#      WHERE user_id = $user_id";
#
$sql = "UPDATE " . USERS_TABLE
user_sig_bbcode_uid = '$signature_bbcode_uid',
WHERE

Explanations like these with the original code lines below are useful I thinks:
"NOTE: the original text is like:"
or
"NOTE: this is a search by part of code lines!
The original lines to find are longer and must look like this (if no MOD has already modify them):"

I think that clearly explain this is the best way to produce the best EMC how-to as possible (with FIND on part of code lines), and help as much as possible newbies to apply instructions of EMC MODs manually (if they want to install this kind of MODs manually)

[Ptirhiik]

Indeed, we all agree (except Ptirhiik perhaps)

Indeed, you definitivly never understood a clue to what I was saying, and I guess this is perfectly volontairy. So thanks to not trolling on this, till you make the effort to understand, and perhaps to get a reflection on it.