Page 1 of 1
How to Comment, the Right Way?
Posted: Sun Mar 20, 2005 1:34 pm
by Ambush Commander
Everyone knows how to comment. Commenting is easy.
But for some reason, I feel as if there's an unspoken standard about
how to comment your code. Like:
Code: Select all
/*
* This is something
*
*user: bang
*
*/
I'm pretty sure this comment does something special (or something like it), but what?
Plus, when I go documenting my scripts, I want to stay consistent and use the same format.
Is there any reason to have a preference between # or // ?
And what does {{{ mean?
And is there anything else about commenting I should know?
Posted: Sun Mar 20, 2005 4:49 pm
by evilmonkey
There is a general way of commenting that is taught at schools and universities (at least here). It works basically like this:
At the top of each program, you write your name, the date, the name of the script/program, and what it's suppossed to do. You may want to explain what it's for, why you wrote it, how to read it, and any conventions you used (i.e. special use of global variables).
Before each function, you have a header that has the name of the function, it's purpose, it's parameters, and it's return. This is the stadard "javadoc" way of commenting.
Any other "in-line" comments should come in as you go along to clarify for the reader of the code.
All in all, your scripts should look like this:
Code: Select all
<?php
/************************
March 20, 2005 *
This is wrtten to show *
Ambush Commander proper *
commenting conventions *
*************************/
//declare all the variables
$var1; //you never actually want to use names like this
$var2;
/****************************
@name: add
@param: $var1, $var2
@return: $sum, integer
@desc: This function takes two integer values and adds them
*****************************/
function add($var1, $var2){
$sum;
$sum = $var1 + $var2;
return $sum;
}
//this adds 2 and 3 and stores it in var1
var1 = add(2,3);
//this adds 4 and 5 and stores it in var2
$var2 = add(4,5);
//this adds var1 and var2 and outputs it
echo add(var1,var2);
?>
Hope this helps!
Posted: Sun Mar 20, 2005 5:54 pm
by Maugrim_The_Reaper
Comment often, in detail if required, and at each stage of the process. A starting header stating wha the file is about, etc. is generally a good idea. Helps a developer find something quickly without reading the whole file.
Just remember what commenting for: ensuring the code makes sense to other developers, or anyone else even. Don't be afraid to state the obvious - not everyone is going to follow your logic...
phpdocumentor like comments (see above) are not a necessity - but are helpful. Single line comments, even a simple "this does that" in the right place can make a huge difference to readability...
Posted: Sun Mar 20, 2005 6:08 pm
by Ambush Commander
Ah... I see. Thanks.
Now, what are these {{{ for?
Posted: Sun Mar 20, 2005 6:12 pm
by feyd
where do you see them?
Posted: Sun Mar 20, 2005 6:16 pm
by Ambush Commander
Don't know, read about it somewhere, I know it has something to do with "folding" and "hiding code". Something with editors and stuff, but I haven't found any editors that support this "folding"
Posted: Sun Mar 20, 2005 6:22 pm
by feyd
oh.. yeah.. there are several editors that support that. It comes under several names like code folding, regions, etc. It doesn't change the code, just allows you to collapse a section of code when you don't want to look at it. I've seen a few that will allow collapsing of any block eg.
where it'd put a [+]/[-] in the margins next to the { or if allowing you to collapse or expand as you wished the block.
Posted: Sun Mar 20, 2005 7:17 pm
by timvw
{{{ and }}} are used by vim as fold markers
more info on phpdocs:
http://manual.phpdoc.org/HTMLSmartyConv ... o.pkg.html
Posted: Mon Mar 21, 2005 4:05 am
by CoderGoblin
I would recommend you look at phpdocumentor. This as far as I know is the "standard" method of adding comments. It is also useful when you get a "javadoc" like HTML reference "site" for documentation purposes.
http://www.phpdoc.org
Posted: Wed Mar 30, 2005 11:32 am
by lastcraft
Hi...
Maugrim_The_Reaper wrote:Comment often, in detail if required, and at each stage of the process. A starting header stating wha the file is about, etc. is generally a good idea. Helps a developer find something quickly without reading the whole file.
This can be a pretty emotive topic. The answer is to do only the commenting you need within your team. If the team prefers looking at PHPDocumentor style web pages (e.g.
http://www.simpletest.org/) then you willhave to add parsable comment blocks. I think it is these taht you refer to as a standard commenting style.
If you have other practices that make commenting redundant, e.g. decent naming, short methods, pair programming, code review, unit testing, design by contract, etc, etc. then don't do it. It will just go out of date and anyway it will slow you down. That is my preferred approach if the team are good code writers.
Your methodology (the collection of practices you adopt) will determine what, if any, comments you need.
yours, Marcus