Page 1 of 2

What is the standard of commenting code

Posted: Fri Mar 24, 2006 2:15 am
by fastfingertips
Hello i different styles of commenting the code so i would like to know how should i comment a:

- class
- method
- property (parameter).

Posted: Fri Mar 24, 2006 2:39 am
by feyd
the particular style you use is a personal choice (although it can be chosen for you when working with others.) As for when to comment. All of the above and more. I tend to try to comment what interaction goes on with each if or other conditional I use. Loops, I tend to note what it's doing at the beginning, but not always. The major route I try to take is, "If I drop off the face of the earth tomorrow, will someone (with no knowledge of the code) know what the code was doing?"

As for style of coding, I see phpDocumentor (Java Documentor/Doxygen) format a lot. I can't say I'm a real fan of it, but it works. I've been experimenting with a really rough port of the XML documentation I last saw in .Net stuff I used to work on. It requires a bit more writing (if by hand) but I think it can be more readable, and certainly is easier to parse when generating documentation. :) I haven't really settled on the children vs attributes debate yet though.

Here's a basic example of a function's comment in phpDocumentor (taken from SimpleTest's UnitTestCase::assertNull()):

Code: Select all

/**
         *    Will be true if the value is null.
         *    @param null $value       Supposedly null value.
         *    @param string $message   Message to display.
         *    @return boolean                        True on pass
         *    @access public
         */
And the same thing in the tentative XML format

Code: Select all

/*
             <function name="assertNull" access="public">
               Will be true if the value is null.
               <parameter name="value" type="mixed">
                 Supposedly null value.
               </parameter>
               <parameter name="message" type="string">
                 Message to display
               </parameter>
               <return type="boolean">
                 True on pass
               </return>
             </function>
         */
The parser I'll write will be able to infer some of details about the function on its own [in PHP 5], so some attributes and/or tags won't necessarily be required.

Posted: Fri Mar 24, 2006 5:18 am
by s.dot
I tend to use a lot of // commenting. // followed by a tab, that is.

of course this has changed as i've progressed in coding.

At first, no comments.
Then /* this */ everywhere, even it it was only one line.
Now, I use a combination and perhaps OVER comment :P

Posted: Fri Mar 24, 2006 7:06 am
by Grim...
I make a point of telling my team to overcomment - it may take longer in the short term, but it saves hours in the long term.

Basically, my rule of thumb is this: "If I have no previous knowledge of what your page / function / whatever does, I should be able to take all the real code away and still know exactly what is going on by looking at the comments that are left behind."

Posted: Fri Mar 24, 2006 7:06 am
by Grim...
Oh, and I'm really bad at commenting :D

Re: What is the standard of commenting code

Posted: Fri Mar 24, 2006 8:40 am
by Roja
fastfingertips wrote:Hello i different styles of commenting the code so i would like to know how should i comment a:

- class
- method
- property (parameter).
I use double slash (//) for comments. I generally put most of the comment at the top of a file, before I define the class. Then I comment, as appropriate, inside the class to document specific items. I deeply avoid "Magic numbers", but if I do use them, I always comment on what the number is.

Posted: Fri Mar 24, 2006 8:48 am
by shiznatix
I hardly ever comment my own code. I know this is a really bad habbit but I hate trying to read code with a thousand comments in it. The comments never make sence to me and never help me out. I understand what someone is trying to do a lot better when I just look at their code.

Posted: Fri Mar 24, 2006 9:53 am
by Benjamin
I'm pretty much at a point where PHP is a second language to me. I can pretty much just read it and I don't really need comments. Once in a while I stumble across something I just don't quite understand, such as a class or something but other than that I really don't care if code is commented or not. So much of the code I see isn't commented that I am used to it. That being said, sometimes I comment, sometimes I don't. Just depends on where the code is going to end up.

Posted: Fri Mar 24, 2006 6:55 pm
by sheila
You may be able to see at glance what the code does but comments will help you see what
the original programmer thought it was doing. And that's very helpful in debugging complicated code.

I sometimes outline a program with comments then fill in the code.

Posted: Fri Mar 24, 2006 7:01 pm
by John Cartwright
agtlewis wrote:I'm pretty much at a point where PHP is a second language to me. I can pretty much just read it and I don't really need comments. Once in a while I stumble across something I just don't quite understand, such as a class or something but other than that I really don't care if code is commented or not. So much of the code I see isn't commented that I am used to it. That being said, sometimes I comment, sometimes I don't. Just depends on where the code is going to end up.
Try opening up someone elses application with thousands of lines without comments and see how far you get :wink:

Personally, I like to write my class first, and then comment next. The comments arn't only neccesarily for my own benefit down the road, but to allow others to follow my reasoning or to input reasons why certain actions were taken.

For instance, lets say one class had some weird bug in it, so you added another method to fix this bug. Now another developers comes along and notices this stupid little method that he can't figure out why you are using.. little does he know it was a bug fix and deletes the method. Now he is back to square one trying to figure out where the bug lies.

Posted: Fri Mar 24, 2006 7:20 pm
by alex.barylski
Grim... wrote:Oh, and I'm really bad at commenting :D
At least your honest :)

Posted: Fri Mar 24, 2006 7:32 pm
by alex.barylski
shiznatix wrote:I hardly ever comment my own code. I know this is a really bad habbit but I hate trying to read code with a thousand comments in it. The comments never make sence to me and never help me out. I understand what someone is trying to do a lot better when I just look at their code.
A lot of programmers have that problem...where they find comments clutter whats going on...

I personally love the mash of green comments against red strings and purple numbers and blue keywords :P

I find that it helps organize my code better actually, but anyways...

My point is, you can still comment like mad and hide your comments when you don't want to see em' that way others have the option...

You use the multi-line comment:

Code: Select all

/*
  Little ditty, about Jack and Diane 
  2 American kids growin up in the heartland. 
  Jacky goin' be a football star 
  Diane's debutante--backseat of Jacky's car 
*/

function do_something()
{
  return 0;
}
Then you use an editor like UltraEdit which supports source folding...

UE recognizes multiline comments and allows you to fold/unfold comments, functions, etc at will...you still have a line or two used up to represent the folded code section, but it beats the heck out of 10 lines or more...

This is what I do anyways :)

Posted: Fri Mar 24, 2006 7:55 pm
by alex.barylski
agtlewis wrote:I'm pretty much at a point where PHP is a second language to me. I can pretty much just read it and I don't really need comments. Once in a while I stumble across something I just don't quite understand, such as a class or something but other than that I really don't care if code is commented or not. So much of the code I see isn't commented that I am used to it. That being said, sometimes I comment, sometimes I don't. Just depends on where the code is going to end up.
8O

If it was hard to write, it should be equally as hard to understand I guess eh??? :P

Not commenting is as bad a habit as not brushing your teeth...and poor commenting is almost just as bad... :)

Posted: Fri Mar 24, 2006 8:31 pm
by Christopher
I definitely prefer unit tests and almost not comments (except for what is needed by a documentor). I have two problems with comments:

1. Comments are mostly useless and just obscure the code.

2. Comments just increase the amount of text that has to be maintained because they have to be updated whenever the code is changed.

As to hypothetical "application with thousands of lines without comments" I really don't see how comments will help you grasp what a 1000 lines of code do. Use cases, unit tests and examples maybe, but not comments.

Posted: Sat Mar 25, 2006 12:04 am
by alex.barylski
arborint wrote:I definitely prefer unit tests and almost not comments (except for what is needed by a documentor). I have two problems with comments:

1. Comments are mostly useless and just obscure the code.

2. Comments just increase the amount of text that has to be maintained because they have to be updated whenever the code is changed.

As to hypothetical "application with thousands of lines without comments" I really don't see how comments will help you grasp what a 1000 lines of code do. Use cases, unit tests and examples maybe, but not comments.
Although I can agree, that in an HLL like PHP, comments are less nessecary than say assembler, in which case their absolutely essential...I cannot agree that they are completely useless.

Perhaps in everyday business logic, using properly named variables and function names, etc, one could deduce the meaning of non-commented code, but I am sure there are instances which would stump even the most seasoned developer without the use of comments in source code or at least slow him/her down while they dig through docs, etc...

Deeply nested recursive functions or esoteric binary operations when used in conjuction with complex nested loops and if statements are not easily decoded even with all the tools of trade and comments included, as well as articles and documents explaining an algorithm, nevermind without comments. :roll:

Comments are not intended to give anyone an overall picture of a system or class or whatever, their used to quickly grasp non-trivial concepts which may not fit well in the domain of documentation or be indicated at all in automated tools like unit tests, flow chart generators, etc...

I agree that there are many ways to help describe code:
- Call graphs
- API documents
- Flow charts
- Unit Tests

And so on....each of which does a good job helping decode...the...meaning...of...code :?

However, IMHO, there is a difference between understanding a system overall and being able to make atomic changes. The latter is where comments usually come in handy and everything else would likely fail.

I understand that commenting is personal choice, but for you to say mostly useless is an understatement...

Perhaps when programming languages resemble natural language more than they do an artificial syntax of such, perhaps then, we can do away with comments all togather, but until that day, I'm afraid I personally advocate the use of comments.

Besides, there are editors which allow you to hide "most" of your comments using source folding...

Wow 8O I can't believe I put that much energy into defending my stance on use of comments :oops:

My apologies for the boring rant :P *ducks under desk*

Cheers :)