The great comments in code
Moderator: General Moderators
The great comments in code
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.
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.
- CoderGoblin
- DevNet Resident
- Posts: 1425
- Joined: Tue Mar 16, 2004 10:03 am
- Location: Aachen, Germany
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
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
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
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.
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.
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...
Sidenote: It's at todays date commented, to protect the innocent following in my footsteps... *cough*
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...
Sidenote: It's at todays date commented, to protect the innocent following in my footsteps... *cough*
http://www.phpdoc.org/ is the quasi standard for commenting.
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
Well it's also quite witty if done correctly. I don't see any harm or anything amateur in having a sense of humorhawleyjr 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.Skara wrote:I generally comment as clear as possible when needed, but be funny at the same time.
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.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.
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.
- Buddha443556
- Forum Regular
- Posts: 873
- Joined: Fri Mar 19, 2004 1:51 pm
Microsoft code is a good example of such unprofessional behavior.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.
Wonder how many comments like "WTF IS THIS HACK FOR?" they'll have to strip?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.
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
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
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