The great comments in code

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

User avatar
infolock
DevNet Resident
Posts: 1708
Joined: Wed Sep 25, 2002 7:47 pm

The great comments in code

Post 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.
Last edited by infolock on Wed Jun 01, 2005 11:23 pm, edited 2 times in total.
User avatar
hawleyjr
BeerMod
Posts: 2170
Joined: Tue Jan 13, 2004 4:58 pm
Location: Jax FL & Spokane WA USA

Post by hawleyjr »

I agree, actually I had a proff. in college who would dock your grade if the spelling in you comments were incorrect.
User avatar
shiznatix
DevNet Master
Posts: 2745
Joined: Tue Dec 28, 2004 5:57 pm
Location: Tallinn, Estonia
Contact:

Post by shiznatix »

i just comment every other line with
//screw you jerk figure it out yourself

:lol:
User avatar
CoderGoblin
DevNet Resident
Posts: 1425
Joined: Tue Mar 16, 2004 10:03 am
Location: Aachen, Germany

Post 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
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post 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.
User avatar
JAM
DevNet Resident
Posts: 2101
Joined: Fri Aug 08, 2003 6:53 pm
Location: Sweden
Contact:

Post 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*
User avatar
patrikG
DevNet Master
Posts: 4235
Joined: Thu Aug 15, 2002 5:53 am
Location: Sussex, UK

Post by patrikG »

http://www.phpdoc.org/ is the quasi standard for commenting.
User avatar
Skara
Forum Regular
Posts: 703
Joined: Sat Mar 12, 2005 7:13 pm
Location: US

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

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

Post 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.
User avatar
hawleyjr
BeerMod
Posts: 2170
Joined: Tue Jan 13, 2004 4:58 pm
Location: Jax FL & Spokane WA USA

Post 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.
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post 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 :)
timvw
DevNet Master
Posts: 4897
Joined: Mon Jan 19, 2004 11:11 pm
Location: Leuven, Belgium

Post by timvw »

I can appreciate return 42; in documentation

(But without the hitchhikers guide to galaxy it's hard to understand ;))
Roja
Tutorials Group
Posts: 2692
Joined: Sun Jan 04, 2004 10:30 pm

Post 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. :)
User avatar
Buddha443556
Forum Regular
Posts: 873
Joined: Fri Mar 19, 2004 1:51 pm

Post 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.
malcolmboston
DevNet Resident
Posts: 1826
Joined: Tue Nov 18, 2003 1:09 pm
Location: Middlesbrough, UK

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