How much do you comment your source code?

No matter what you think the "perfect amount" of code commenting is, let's agree that high-quality comments are important in open source.
265 readers like this
265 readers like this
A bunch of question marks

Opensource.com

While it may be true that the best code is self-documenting, even the clearest written source code requires adequate documentation in order to be quickly parsed and understood by human readers.

In practice, though, where and how much to comment is much more up to the individual developer to decide than elements of the code itself. The compiler or interpreter doesn't generally care about your comments; after all, they're not for it, they're for us humans. And so while some organizations and projects will offer guidelines, commenting styles are much more open to interpretation.

In general, being clear and concise with your comments will be appreciated. But particular within open source, you don't have the luxury of assuming that other developers looking at your code are familiar with the context in which it was written. Everyone is new to the project at some point, and you can't count on them understanding the project's history, its quirks, or the libraries it uses. New contributors may not be native speakers of your language, either.

And so well-written and well-placed comments are an important part of your project's documentation. Are you making sure that your project's code is as accessible as it can be?

How often do you comment? Do you think you comment frequently enough? Let us know what you think!

I use technology to make the world more open. Linux desktop enthusiast. Map/geospatial nerd. Raspberry Pi tinkerer. Data analysis and visualization geek. Occasional coder. Sysadmin. Web maker. Red Hatter since 2013.

9 Comments

I usually comment before I code. This allows me to follow a clear and concise thought pattern. I make it a part of my pseudocode. I've found that 30 minutes of writing what I want the code to do, saves me hours bashing my face against the keyboard trying to code my way out of a corner. A clear understanding of where you're going can only be done ahead of time.

Real programmers do not comment - the code is obvious. ;-)

Well, to be honest, I tend to use implementation free commenting as *Doc style ie. /** .... */ and will comment some "special things" implemented with /* ... /*.

"Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious." Fred Brooks, The Mythical Man-Month

The code tells you how. The comments tell why. That is, they tell the changes to your data structures (tables) the code is making.

In reply to by Jukka (not verified)

The problem with this survey is that multiple answers often apply. For example, for me "Hardly at All" is the same as "I think I've hit the sweet spot."

Look, if you write muddled code, no amount of explanation will make it clear, and if your code is muddled it seems likely that your explanation will be, too. Also, commentary on the code is never checked for correctness and is very rarely updated.

If you write clear code, people can just read it and see what you did, no explanation needed. Sometimes, like Mr. Hilliard, I write comments in advance of the code to record the steps of the process, but I haven't written pseudocode in many years.

The thing is, all the code will tell the reader is what and how things are done. If you've done this for a while, and I've done this for a long while, you can usually get inside the head of whoever wrote it and often figure out why they do what they do, but that's advanced. So, comments should focus on the WHY you're doing what you're doing.

To make your code easier to follow, you should do as Dr. Perlis said and establish and follow idioms as you write. That will do far more to help your reader understand what's going on.

There are some interesting comments here. I try to comment most lines, I thing I can ignore the 'Else' and 'EndIf' lines.This is not to help others but to remind myself what I was doing. I have found many errors doing this or cases where code simplification was possible. I recommend it, you may be suprised what you find.

YMMV (a lot), but usually I reserve comments for the higher-level stuff. For example, I prefer to comment function specs (prototypes for you C people :-)) so that a person looking at my code know *what* a function/method does. Also, I usually put comments in the head of my packages, so that people know what is the duty of that package. It is very, very unusual that I put comments in the actual code, unless I am using a very involved algorithm with non-obvious actions. I prefer to give long, descriptive names rather than resorting to comments. For example, if you see

function Exist_Device(Serial_Number : Integer) return Boolean
is
begin
for I in Device_Table.Range loop
if Device_Table(I).Serial = Serial_Number then
return True;
end if;
end loop;

return False;
end Exist_Device;

is pretty clear what it does, without the need of comments.

As someone who has done maintenance programming for decades, and spent a lifetime looking at other people's code, the first thing I usually do is delete the comments. They're non-functional, so there's no guarantee that they have anything at to do with the code that's actually running. They might have once, but the code may have changed, and the comments are no longer correct.

You can't know, so you can't trust them. Delete them so the actual code is less cluttered, and then work to understand the actual code. Then work with it.

So, if experienced maintenance programmers like me go out of the way to ignore your comments, how much value are they actually adding?

I do the opposite I find someone didn't comment it, I'm adding some as I want to ensure someone later doesn't have to waste time figuring out what something does.

if the comment is pointless, yeah I'll delete it, but I approve of people "showing their work" so another dev can understand it.

In reply to by David Barrett (not verified)

I always document my code, even if it makes sense. I do it because its good practice and I can make documentation for anyone who needs to use it.

I know it can get heated between developers on if you should document, I know its split on my team.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.