Would you like a side of comments?
Posted on 05.09.2009 03:21 pm
Comments in source code are a wonderful tool for many reasons. The main reason for a comment is to explain why a certain code is executed.
Take this Fibonacci code for example:
unsigned short a = 0;
unsigned short b = 1;
unsigned short c = 0;
while(b < 100)
{
cout << b << endl;
// We use c as a temporary number while we add a with b
c = b;
b = a + b;
a = c;
}
The comment serves as a reminder why c is being used. In most cases we know why c is used but there might be a time when we skim over the code and wonder why we are using three variables.
But there is another way to use comments that I use constantly but I've rarely seen others do. And that is to use comments as a spacer.
This method is actually used a lot without many people knowing it, and that is when you comment a function to state what it does.
When this is done in a file that has a collection of functions (a class file for example), it serves as an index to the file. Making it possible to scroll through quicker.
But when you're dealing with files that aren't that logically split up, that's when I use this method as well.
Let's take a part of the comment controller I have here.
/* If the user did not solve the mini math problem */
if(!isset($_POST["minimath"]) ||
(isset($_POST["minimath"]) && empty($_POST["minimath"])))
{
$error["empty_minimath"] = "You must solve the math problem!";
}
/* If the mini math problem is wrong */
if(isset($_POST["minimath"]) && !empty($_POST["minimath"]))
{
if($_POST["minimath"] != $_SESSION["answer"])
{
$error["empty_minimath"] = "Math problem wrong!";
}
}
The actual code is very simple, but as the checks I need to do in that controller grow, it becomes harder to work efficiently in. So even though I know exactly what each piece does. I comment it for my future's sanity.
Update: As Konrad pointed out in the comments. The naming of the variables is poor in the first example but this is only to serve as a rough example of a type of comments.
1 4 Like it or hate it? - Comment (2)
Konrad
0 2 / Posted on 05.09.2009 07:17 pm
The first comment in your posting is actually a very good example for bad use of comments. Much better would have been to use a good variable name for `c` (and even `tmp` would have served here to convey the same amount of information as the comment). The second use of comments – to structure a long method – is actually the one I use most often. Of course, it would be better to use separate methods instead and then chain them in one main method which would basically consist of calling subordinate routines. However, this would often necessitate promoting a lot of local variables to a larger scope (e.g. `private`) which is something I eschew. So yes, that’s the kind of comments I can get behind.
Ólafur Waage
0 0 / Posted on 05.09.2009 09:08 pm
Yes I agree that naming of the variables in the first example is poor. And in many cases just a good name for a variable will remove the necessity of a comment.I just wanted to throw in a dumb example since my main point was the second type of comments.
Process time: 0.009681 seconds
