What is the standard of commenting code
Moderator: General Moderators
-
fastfingertips
- Forum Contributor
- Posts: 242
- Joined: Sun Dec 28, 2003 1:40 am
- Contact:
What is the standard of commenting code
Hello i different styles of commenting the code so i would like to know how should i comment a:
- class
- method
- property (parameter).
- class
- method
- property (parameter).
- feyd
- Neighborhood Spidermoddy
- Posts: 31559
- Joined: Mon Mar 29, 2004 3:24 pm
- Location: Bothell, Washington, USA
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()):
And the same thing in the tentative XML formatThe 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.
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.
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
*/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>
*/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
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
Set Search Time - A google chrome extension. When you search only results from the past year (or set time period) are displayed. Helps tremendously when using new technologies to avoid outdated results.
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."
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."
Re: What is the standard of commenting code
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.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'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.
- John Cartwright
- Site Admin
- Posts: 11470
- Joined: Tue Dec 23, 2003 2:10 am
- Location: Toronto
- Contact:
Try opening up someone elses application with thousands of lines without comments and see how far you getagtlewis 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.
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.
Last edited by John Cartwright on Fri Mar 24, 2006 7:59 pm, edited 1 time in total.
-
alex.barylski
- DevNet Evangelist
- Posts: 6267
- Joined: Tue Dec 21, 2004 5:00 pm
- Location: Winnipeg
-
alex.barylski
- DevNet Evangelist
- Posts: 6267
- Joined: Tue Dec 21, 2004 5:00 pm
- Location: Winnipeg
A lot of programmers have that problem...where they find comments clutter whats going on...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.
I personally love the mash of green comments against red strings and purple numbers and blue keywords
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;
}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
-
alex.barylski
- DevNet Evangelist
- Posts: 6267
- Joined: Tue Dec 21, 2004 5:00 pm
- Location: Winnipeg
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.
If it was hard to write, it should be equally as hard to understand I guess eh???
Not commenting is as bad a habit as not brushing your teeth...and poor commenting is almost just as bad...
- Christopher
- Site Administrator
- Posts: 13596
- Joined: Wed Aug 25, 2004 7:54 pm
- Location: New York, NY, US
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.
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.
(#10850)
-
alex.barylski
- DevNet Evangelist
- Posts: 6267
- Joined: Tue Dec 21, 2004 5:00 pm
- Location: Winnipeg
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.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.
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.
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
My apologies for the boring rant
Cheers