How to Comment, the Right Way?

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

Post Reply
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

How to Comment, the Right Way?

Post 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?
User avatar
evilmonkey
Forum Regular
Posts: 823
Joined: Sun Oct 06, 2002 1:24 pm
Location: Toronto, Canada

Post 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!
Last edited by evilmonkey on Wed Jan 21, 2009 10:41 am, edited 1 time in total.
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

Post 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...
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post by Ambush Commander »

Ah... I see. Thanks.

Now, what are these {{{ for?
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post by feyd »

where do you see them?
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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"
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post 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.

Code: Select all

if(foo)
{
  // inside a block
}
where it'd put a [+]/[-] in the margins next to the { or if allowing you to collapse or expand as you wished the block.
timvw
DevNet Master
Posts: 4897
Joined: Mon Jan 19, 2004 11:11 pm
Location: Leuven, Belgium

Post by timvw »

{{{ and }}} are used by vim as fold markers :)

more info on phpdocs:
http://manual.phpdoc.org/HTMLSmartyConv ... o.pkg.html
User avatar
CoderGoblin
DevNet Resident
Posts: 1425
Joined: Tue Mar 16, 2004 10:03 am
Location: Aachen, Germany

Post 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
lastcraft
Forum Commoner
Posts: 80
Joined: Sat Jul 12, 2003 10:31 pm
Location: London

Post 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
Post Reply