June 23, 2004

When to Comment Code

Use comments to explain what the code does and why the code needs to do that function. Also use comments to describe how the code performs to a newbie. Newbies will be learning from your code.

Now here is the key when it comes to coding, if the code is tricky or difficult to follow. Do not use a comment to fix code. The intent of a comment is so that someone can pick up the code and immediately understand it, not walk through the code line by line with the comments as a bible. Make the code easier to understand, try to keep it simple, and remove the trickiness.

Another item is that one should understand there is an audience that reads the comments. Comments should not convey zealous technological beliefs, the comment is not the forum for that. A discussion with the team is the forum, not the coding comment.

In CF comments should be in the CFML style (<--- comment --- >), so it is not readable in the browser.

When you make a change, comment it, and identify the date and your initials.

If you want to leave a note about a bug to be fixed or functionality to be added, place a TODO: in front of the actual comment, so people now what to search for.

<--- 2004-06-05 (EVN) TODO: Incorporate everyone'se feed back --- >

Don't delete blocks of code in production, comment them out with the date and reasoning for removal. In my opinion it is just good practice not to delete production code.


In pages have the following
<---
Author:
Description:
Parameters:
In:
Out:
Usage:
Documentation Location:
Based on:
Date Created:
Template Type:
User Owner:
Summary:

$Log:
Revision 1.2 2004/06/04 EVN
Fixed db SQL transaction

Revision 1.1 2004/06/01 EVN
Initial Version into production
--->

These really help when trying to discover the history of a project and the changes incurred.

Posted by Elyse at June 23, 2004 6:47 AM | TrackBack
Comments

Comments are so important, but I still get blank stares from developers, as if it's a waste of time, or not that important.

It comes again from that lack of long-term vision.

I always say, "What if you died, how would anyone, not you be able to figure out that code?"

What if you wanted to modify it in a year, how would you know where to modify and how, what and so forth.

It's nice to have a functioning application, but it's much nicer to have solid, quality, stable, documented code.

Good work Elyse!

Posted by: Craig M. Rosenblum at June 23, 2004 3:02 PM

Well spoken, both the post and that first follow-up comment.

I have the same problem with many of my team members. Nobody is concerned with the "what if you died tomorrow" scenario. Or more realistically, what if you're not reachable tomorrow and *I* have to fix something in your code?!

Another thing programmers (at least the ones I seem to work with *g*) overlook is the importance of self-documenting code. Comments aren't always as necessary if I can tell what your variable and function names do by how they're named. If you build an order entry system, would you refer to the order number by "order_num" or "o"? Unfortunately, the incorrect answer is what's been used on several projects I came into, too late in the process to revert to a normal variable name.

Lately I've preferred to keep my log/history of changes in the version control software we use, as code is checked in. the changes are still logged, in date order, and are neatly out of the way now, keeping the CFM files a tad more light weight.

Posted by: Nolan at June 23, 2004 8:47 PM

Want to hear something really funny?

Over 2 years ago, after the dot-bomb, I was job hunting, and one company had me look at their code, and they are supposed to be a top web shoppe.

They had no commenting, indenting to their code. And I was supposed to look at them as if this was great code, and how I could improve it/change it, whatever.

I have a simple saying now.

The Quality of the Code has to match the Quality of the Application in terms of pretty, functionality so forth. Each must be given equal weight.

And don't get me started on different styles of indenting

Posted by: Craig M. Rosenblum at June 24, 2004 10:18 AM