Page 1 of 2

The great comments in code

Posted: Wed Jun 01, 2005 10:31 pm
by infolock
You know, I sit here contemplating applications in progress, ways that I have to build it to be as productive as possible. THings I need to impliment that are going to make it versatile and easily used in conjunction with client-side functionality. I then start thinking about what it's gonna be like when another developer has to read this code and understand it based on my comments.

I really think I didn't ever respect good comment usage until I had to do my first revision of another person's code and their coding style. Comments, to me, are one of the best things in the world you can add to your application/script that will make the rest of the world love it even more. Well documented comments can add the ability to not only use it, but understand why/how this particular program was written, and make you feel comfortable about having to make any future changes without wondering "now..what the hell does this do? Better yet, why?"

For instance: phpMyAdmin has a superb comment stack in it's applications. I mean, their interface for MySQL is not the most advacned (it's quite plan Jane actually), but we love it for what it does. But what allowed us to respect it even more compared to other methods/scripts that do the same thing, was their very easy to follow comments they placed. index.php is about one of the best examples that I could give.

So what I'm trying to say is, well documented and organized comments within a program can give a serious jump in it's overall popularity with the open sournce community/co-workers. I just wish more people followed that mentality. We then would have a community that not only learns together, but a community that slowly began coding with diversity, adaptability, and more than anything else work on the same mind-set.

Posted: Wed Jun 01, 2005 10:46 pm
by hawleyjr
I agree, actually I had a proff. in college who would dock your grade if the spelling in you comments were incorrect.

Posted: Thu Jun 02, 2005 1:43 am
by shiznatix
i just comment every other line with
//screw you jerk figure it out yourself

:lol:

Posted: Thu Jun 02, 2005 2:43 am
by CoderGoblin
Annotation/Comments are required in code even if you do not think others will ever look at your code. It is often amazing how you go back to code you may have wrote a couple of years ago and need to change something.

Once useful method to create comments is to sketch out the progress of the code in "pseudocode" (simplified non-parsing code) prior to filling out the program with the actual code.

Also look at phpDocumentor

Posted: Thu Jun 02, 2005 5:47 am
by Chris Corbyn
Comments are something I've ALWAYS considered inportant right from the very beginning.

As already mentioned, you can often go back to something months later and comments are certainly gonna be a big help. I'm not saying we'd all fall down without them but I think it makes the whole process more efficient when you pick old code up cos you dont have to study it quite so much.

I even add stupid comments which you *would* think everybody should know but it doesn't hurt. IMHO it makes your code look much more visually appealling too. I like to share code where I can so comments are vital for this reason alone.

Another thing I find with commenting code is that you have to actually think about what you're doing and why you are doing it as you code it... as opposed to just churning out a heap of code which works. This means that you often consider a better approach while you work on it and generally produce a more clean-cut application as result.

Finally.... I find it helps to keep a log of events (a history) in a comment block either at the start or the end of the file so that others can see what bugs you found and how they were fixed among other things.

Posted: Thu Jun 02, 2005 8:32 am
by JAM
Only thing I can do, is agree...

Not very long ago I looked at some code in a older, big project that I was about to help convert to a different format. Suddenly I thought to myself; "-Hmmm, what does this do...".
2 minutes later I realized that I've made it myself... :oops:

Sidenote: It's at todays date commented, to protect the innocent following in my footsteps... *cough*

Posted: Thu Jun 02, 2005 10:03 am
by patrikG
http://www.phpdoc.org/ is the quasi standard for commenting.

Posted: Thu Jun 02, 2005 6:54 pm
by Skara
I generally comment as clear as possible when needed, but be funny at the same time.
Instead of...
//this function returns the sum of the two numbers
I'll put something like...
//returns the sum of the two numbers (just in case you can't figure it out yourself)

^_^;

Posted: Thu Jun 02, 2005 7:11 pm
by Ambush Commander
Commenting code is a good way of re-acquainting yourself with code you wrote but were too lazy to comment and as a result forgot how it worked.

Posted: Thu Jun 02, 2005 7:18 pm
by hawleyjr
Skara wrote:I generally comment as clear as possible when needed, but be funny at the same time.
This style of coding is OK for your personal projects. But if you are doing any professional projects. Typically humor in comments is perceived as amateurish.

Posted: Fri Jun 03, 2005 2:45 am
by Chris Corbyn
hawleyjr wrote:
Skara wrote:I generally comment as clear as possible when needed, but be funny at the same time.
This style of coding is OK for your personal projects. But if you are doing any professional projects. Typically humor in comments is perceived as amateurish.
Well it's also quite witty if done correctly. I don't see any harm or anything amateur in having a sense of humor :)

Posted: Fri Jun 03, 2005 2:51 am
by timvw
I can appreciate return 42; in documentation

(But without the hitchhikers guide to galaxy it's hard to understand ;))

Posted: Fri Jun 03, 2005 5:16 am
by Roja
hawleyjr wrote: This style of coding is OK for your personal projects. But if you are doing any professional projects. Typically humor in comments is perceived as amateurish.
I'd disagree here. Windows 95, Netscape 4, every version of Quake, Linux, and other programs all have funny comments in the source code, and every one of them is pretty much the polar opposite of amateurish.

Its a personal opinion at best, but my professional experience shows that the people who are likely to look at source code are the people with a sense of humor and appreciation for witty source code comments. :)

Posted: Fri Jun 03, 2005 5:47 am
by Buddha443556
hawleyjr wrote:This style of coding is OK for your personal projects. But if you are doing any professional projects. Typically humor in comments is perceived as amateurish.
Microsoft code is a good example of such unprofessional behavior.
techrepublic wrote:Microsoft to release more source code?

Having gathered feedback from customers, Burke said he would pursue the plan to release the Windows Forms code in the most expedient manner possible. Most likely, he said, Microsoft would strip out human-readable comments within the code, which could have references to specific customers or inappropriate language.
Wonder how many comments like "WTF IS THIS HACK FOR?" they'll have to strip?

Usually I try to make sure ever function, class or method has a header comment at very least. No one else usually see my source code but comments sure help month later when a customer needs something changed.

Posted: Fri Jun 03, 2005 5:54 am
by malcolmboston
the last few posts about microsofts source code etc....

It is absolutely ridiculious to be 'having a go' for there source code, windows 2000 alone is said to be around 30m lines of code, in C++ (a much harder programming language than PHP) of course its going to have hacks, odd flawed areas etc. most of the guys here are used to writing a few hundred lines. some of us are used to developing full-fledged application which can run to quite large but not on the same scale (my work project is curently upto 17k) there is a major difference in 17k + 30m, i have plenty of flawed area's in my design and its not even a fraction of that, couple that with hundred / thousands of people colloborating, its only gonna cause problems.

Its a pretty lame argument tbh