Pete Freitag Pete Freitag

How to Comment Code Better

misc

Ryan Campbell has posted some good tips on practical approaches to writing better comments.

His article should help you find the median between over commenting, and not commenting enough.

Commenting your code is like cleaning your bathroomyou never want to do it, but it really does create a more pleasant experience for you and your guests...

there are a lot of tough, but fundamental questions out there like what does "frequently and appropriately" mean? Because there are a million different beliefs and contradictions on the subject, I created this brief overview to present my findings

Like this? Follow me ↯


How to Comment Code Better was first published on August 01, 2005.

If you like reading about comments, code, programming, or tips then you might also like:

Comments

"placeholders" like hint and displayName are (IMHO) a great backhand way of commenting code.

I'd just like to see a hint attribute on cfparam (any chance, do ya reckon?)

my 2c
barry.b
by barry.b on 08/02/2005 at 2:09:31 AM UTC
Hi, I ws searching everywhere for this particletree article, but they all are just links to the same one, which is missing now. Do you have the article in complete? or atleast where can I find it?
by manoj on 11/24/2005 at 7:51:09 AM UTC
A search on Particle Tree yielded the following:

http://particletree.com/features/successful-strategies-for-commenting-code/
by Cadoc on 04/12/2006 at 5:57:08 PM UTC
Pete:

<quote>
Commenting while you code forces you to make sure your logic ?sounds right.? Plus, your comments are going to be more accurate when the understanding of what?s going on behind-the-scenes is fresh in your mind.
</quote>

has writing pseudocode beforehand fallen out of favour? do ppl no longer map out what they want to do (in pseudocode), use that as comments in the source and then add real code around it?

are all my habits (that have served me well) now "old hat"?
by barry.b on 04/12/2006 at 7:53:14 PM UTC