Comments are More Important than Code

CowboyRobot writes "I was going through some code from 2002, frustrated at the lack of comments, cursing the moron who put this spaghetti together, only to realize later that I was the moron who had written it. An essay titled Comments Are More Important Than Code goes through the arguments that seem obvious only in hindsight - that 'self-documenting' code is good but not enough, that we should be able to write code based on good documentation, not the other way around, and that the thing that separates human-written code from computer-generated code is that our stuff is readable to future programmers. But I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized. Who's right?"

Even more annoying...

I used to grade student's code as a TA at my university, and I'll tell you what is more annoying than NO comments, this:

printf("Encrypt message..."); /* print "Encrypt message..." to the console */

and then followed by about 150 lines of uncommented spaghetti code

Top Ten Code Comment Do's List

1. Comment each function
- Function name
- what it does
- parameters
parameter name - what is is for and any restrictions on it (i.e., must not be null)
- return value (all possible return values)

2. Add comments to each file you modify so that over time, the file becomes better documented

3. Add ASSERT() like comments and ASSERT() or equivalent to your code

4. Use dividing comments like a line of dashes to seperate blocks of code

5. Put in a '?' comment for code that you do not understand (good for function headers)

6. Avoid stupid naming schemes for your local variables since that makes it harder to comment

7. Review your code for both logic and comment completeness after you code it before committing it to version control

8. Tag your bug fixes, code enhancements with a comment followed by a dash, date, and your initials. This is essential for large projects or for anything you will be working on for more than 6 months.

9. Format your comments so that multiple line comments line up on the left hand side (increases readability)

10. Don't count on java doc or equivalent as being good enough code documentation.

Re:Top Ten Code Comment Do's List

1. Comment each function
- Function name
- what it does
- parameters
parameter name - what is is for and any restrictions on it (i.e., must not be null)
- return value (all possible return values)

/*
* Function: p-inc
* Purpose: adds one to a positive integer
* Input: x, the integer to be incremented.
* Possible return values: 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 255, 256, 257, 258, 259, 260, 261, 262, 263, 264, 265, 266, 267, 268, 269, 270, 271, 272, 273, 274, 275, 276, 277, 278, 279, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 297, 298, 299, 300, 301, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 316, 317, 318, 319, 320, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, 331, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356, 357, 358, 359, 360, 361, 362, 363, 364, 365, 366, 367, 368, 369, 370, 371, 372, 373, 374, 375, 376, 377, 378, 379, 380, 381, 382, 383, 384, 385, 386, 387, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 425, 426, 427, 428, 429, 430, 431, 432, 433, 434, 435, 436, 437, 438, 439, 440, 441, 442, 443, 444, 445, 446, 447, 448, 449, 450, 451, 452, 453, 454, 455, 456, 457, 458, 459, 460, 461, 462, 463, 464, 465, 466, 467, 468, 469, 470, 471, 472, 473, 474, 475, 476, 477, 478, 479, 480, 481, 482, 483, 484, 485, 486, 487, 488, 489, 490, 491, 492, 493, 494, 495, 496, 497, 498, 499, 500, 501, 502, 503, 504, 505, 506, 507, 508, 509, 510, 511, 512, 513, 514, 515, 516, 517, 518, 519, 520, 521, 522, 523, 524, 525, 526, 527, 528, 529, 530, 531, 532, 533, 534, 535, 536, 537, 538, 539, 540, 541, 542, 543, 544, 545, 546, 547, 548, 549, 550, 551, 552, 553, 554, 555, 556, 557, 558, 559, 560, 561, 562, 563, 564, 565, 566, 567, 568, 569, 570, 571, 572, 573, 574, 575, 576, 577, 578, 579, 580, 581, 582, 583, 584, 585, 586, 587, 588, 589, 590, 591, 592, 593, 594, 595, 596, 597, 598, 599, 600, 601, 602, 603, 604, 605, 606, 607, 608, 609, 610, 611, 612, 613, 614, 615, 616, 617, 618, 619, 620, 621, 622, 623, 624, 625, 626, 627, 628, 629, 630, 631, 632, 633, 634, 635, 636, 637, 638, 639, 640, 641, 642, 643, 644, 645, 646, 647, 648, 649, 650, 651, 652, 653, 654, 655, 656, 657, 658, 659, 660, 661, 662, 663, 664, 665, 666, 667, 668, 669, 670, 671, 672, 673, 674, 675, 676, 677, 678, 679, 680, 681, 682, 683, 684, 685, 686, 687, 688, 689, 690, 691, 692, 693, 694, 695, 696, 697, 698, 699, 700, 701, 702, 703, 704, 705, 706, 707, 708, 709, 710, 711, 712, 713, 714, 715, 716, 717, 718, 719, 720, 721, 722, 723, 724, 725, 726, 727, 728, 729, 730, 731, 732, 733, 734, 735, 736, 737, 738, 739, 740, 741, 742, 743, 744, 745, 746, 747, 748, 749, 750, 751, 752,

Re:Top Ten Code Comment Do's List

* Oh man... I'm so tired of typing these numbers!

You should have written a function to generate the list of numbers for you:

/*
* Function: num_list
* Purpose: Returns a list of positive integers greater than one
* Input: x, the largest positive integer in the list.
* Possible return values: "2", "2, 3", "2, 3, 4", "2, 3, 4, 5", "2, 3, 4, 5, 6", "2, 3, 4, 5, 7", "2, 3, 4, 5, 6, 7, 8", "2, 3, 4, 5, 6, 7, 8, 9", "2, 3, 4, 5, 6, 7, 8, 9, 10", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19", "2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20",

* Hmmm, I think I need a new function to generate the comment for this function...
*/

Re:Top Ten Code Comment Do's List

1. Comment each function
- Function name
- what it does
- parameters
parameter name - what is is for and any restrictions on it (i.e., must not be null)
- return value (all possible return values)

****

I really hate having parameters documented in a comment block above the function declaration, because it seldom gets updated when the function signature itself is changed.

I worked with a guy who used to format his functions like this:

void my_func( // My function does foo
int arg1, // arg1 documentation
char * arg2, // arg2 documentation
...
)
{
// Function guts go here
}

The nice thing about this method, although the "look" of a function is broken up, is that when you add or change parameters, the programmer is a lot more likely to change the documentation as well.

When you're under the gun to get the code out, the less the developer has to do to change the docs, the more likely it is they will be changed.

Re:Top Ten Code Comment Do's List

We comment all functions and classes using the Doxygen format. This means that the comments can be used to generate HTML, PDF or man pages for the functions and classes. It will also generate call trees if required. Very useful.

Re:Top Ten Code Comment Do's List

The nature of the language should affect the number and style of comments.
I'm working with a 4GL, and the stupid comments are driving me more insane, especially the GPs no8 - tagging. I HATE tagging with a vengeance - that's what version control is for. Even worse is the unbelievably moronic practice of commenting out the old code and putting the changed line below it. We get one line of code replaced by 3 lines of comment and a liine of code - the comments are two lines of tags marking the start and end of the changed block and the old line of code - which is often only 1 character different from the new line. I WANT TO HIT THE WHOEVER STARTED THIS - REPEATEDLY.
For example I have been working on a 900 line program where 400 lines are 'comments' - sometimes you only see 1 line of code per page. Now imagine the effect upon search tools - you want to use find+grep to look for code to change, and 95% of the hits are 'comments'. It's got to the stage where I have written a program to strip all the comemnts for our code and save the result. Don't get me wrong I like real comments - ones that tell me something useful like why the code was written, or any gotchas - but when the signal to noise ratio is this low I won't even worry about losinginformation, the performance hit of all this garbage is too much.

Please, don't comment for the sake of it, comment only when you have something useful to tell the next coder to read the program - but do write these informative comments.

Re:Top Ten Code Comment Do's List

This is what code versioning does. And it does it a lot nicer then you could ever hope to acheive with your method. When you do enough work with your system, it ends up that there are 60% commented lines, with 40% real lines. Trying to go backwards 1 week would create tons of problems. If there are too many useless comments, nobody will ever read any comments, or feel like putting good ones in.

I must respectfully disagree.

The three items you seem to object to all have fairly legitimate uses in some computing contexts.

1. Comment each function
- Function name

Why do you need to repeat the name of the function? It's right there in the code.

Yes, and in some contexts that is precisely the problem. Depending on the language and editor(s) you are using, embedding the function names in comments can be very useful.

For example, if I use an "FC" command in a Unisys 2200 mainframe editor (say ED or UEDIT) to show all lines starting with "C" (comment lines) in a Fortran program, the results will be confusing if the function names themselves are not specified in a comment line. All I will see is comments with no context.

By adding the subroutine or function names in the related comments themselves, that missing context is restored.

5. Put in a '?' comment for code that you do not understand (good for function headers)

Code with personal annotations should never be released.

While I agree with this part,

If you don't understand it, you shouldn't be working with it; go find someone who does understand it instead, or stop and work it out.

this part of your comment seems limited to "perfect world" scenarios only.

I've spent most of my career working on mainframe code that was either originally written by people at other organizations or companies, or that was written so long ago that the original designers and coders were either retired or deceased.

When making a first pass at understanding such code, I've found it to be quite useful to leave various comments in the code so I have a good idea about my level of understanding the next time I have to come into that area of code.

I've also found such comments useful when left in the code by others, since it reflects their level of understanding as well. Some of the stuff I'm looking at now was originally coded in the early 80's and rewritten by my predecessor, and the comments he's placed in the code have proven to be invaluable to me, even though some of them were speculative in nature. Something like "What does this code do?" in his comments often alerts me to a tricky part in the logic that I'll want to pay special attention to.

FWIW, question marks and other comments/speculations are commonly used when working on someone else's previously-written code, at least in my experience, especially when that code is only intended for use in-house (the source is not released to customers).

8. Tag your bug fixes, code enhancements with a comment followed by a dash, date, and your initials. This is essential for large projects or for anything you will be working on for more than 6 months.

Once again, nothing with personal annotations should ever be released into source control. Not only should I not need to know who wrote or changed a particular snippet of code to fix a bug, I shouldn't even be able to tell by looking at the code.

When working on code that was written in-house, and which is intended to stay in-house, I *want* to know who made a certain change and why it was done. That type of notation can save me (or another support programmer) a lot of time.

While those types of details might be handled by the source control system(s) that you work with, keep in mind that some of us work on platforms where analogs to the UNIX-like source control systems many people are used to simply do not exist (and often such a thing isn't really needed).

When I did Unisys A-series mainframe contract work at a small company in southern Minnesota, they used the unparsed end of each COBOL line as a comment area, and one always placed their initials and a date there so people knew who did which changes and when those changes were created. The editor they used (CANDE) even had a special setting to automagically place a change mark on the end of each line that was modified.

A si

Re:Even more annoying...

hah I also grade as a university TA, and let me tell you what is more annoying than that... people who don't know how to indent their code, and want you to help debug it! Ahhhhh!!!!!

Re:Even more annoying...

1994 is calling and it wants its Sparc IPX back.

Re:Even more annoying...

An emacs post replying to an Eclipse post and you choose to point out how bloated emacs is?

Re:Even more annoying...

I came across that with a grad student at my univ. I told him that I couldn't read his code because it wasn't indented. He said, "I was going to back and do that later." WTF? I thought that was going to be the Quote of The Day, but it turned out he wasn't done yet. I started indenting every line as I walked through a function. Seeing this, he inquired, "How are you moving those lines over?" My answer? "Tab."

Shocking.

Re:Even more annoying...

Heh.. his roommates probably think he's having some marathon maturbation session when he's in his one of code-indenting sessions (presumably with the space bar?)

semicolons in column 80

I had a co-worker who needed a little help with his program. It was C code, but all the semicolons were in column 80, arranged in a nice column. Yikes. He casually said "what, you've never seen that?". Turns out that part of his problem was that he was using float to represent a byte position in an extremely large file. He knew enough that UINT32 wouldn't do it, but ...

Re:Even more annoying...

in vim, with C code, you can just do:

gg=G

and it will reindent a file for you....

I hate programmers who refuse to learn about their tools.

Re:Even more annoying...

You know whose fault that is? The morons that mark you down if you don't comment trivial programs like Hello World.

I actually ended up doing three introductory programming courses at college and university (overlap in curricula), and I've been marked down for not including this type of comment in all three courses.

printf("Hello, world!\n"); /* send "Hello, world!" to the console and move to the next line. */

The problem is that they try and teach you to write comments prematurely. When all most people on the course can write are programs like Hello World, they really can't see the use of comments and there are no good examples to give. The use of comments should come after things like functions etc IMHO, so that students can actually see how comments can be useful.

Re:Even more annoying...

Ive been in enough classes this year (well below my level.. dammit, I need the "letters") that Ive come to the conclusion that introductory programming courses are taught all wrong.

Write 5 lines. Write 20 lines. Write 100 lines. Of useless and pointless code.

What should be done is: Take this 1000 line programme. Add on 5 lines. Add on 20 lines. Add on 100 lines. Beacuse that would require being able to read code, too. Being able to understand what is already there is frequently more then half the battle. Saying "What the fuck does this mean?" a few dozen times is the only way to get to write comments. Being a sysadmin, rather then a full time programmer, this took me litteraly years to learn. And it was usualy "What the fuck were you doing here, brain? Dammit, one of these days were going to have to start commenting our code."

About 6 months ago, I read through a project request on one of these ebay-for-coders sites. Language optional; 1 comment per 5 LOC, but if using Perl, 1 comment per 2 LOC.. With requrements like that you are only asking to get BS comments like "Print X to the console".

Re:Even more annoying...

What should be done is: Take this 1000 line programme. Add on 5 lines. Add on 20 lines. Add on 100 lines.

Better yet - remove 5 lines. remove 20 lines. remove half the lines ... and it better still work!

Re:Even more annoying...

What should be done is: Take this 1000 line programme. Add on 5 lines. Add on 20 lines. Add on 100 lines.

Better yet - remove 5 lines. remove 20 lines. remove half the lines ... and it better still work!

Pfft! Just remove the comments! ;-)

z

Actually, you illustrate a bigger problem

It's not just that the programs to write are small, it's that they're write-only. You write them once, get graded, that's it. We churn generation after generation of students who are taught that code is written once, then never ever maintained.

Sure, you learn lots of things about design, software engineering, etc, in university, but they're pure theory. And seemingly useless theory at the moment. There is _nothing_ to illustrate there why some code organization is good, and why spagetti code is bad. All those lessons about maintenance as wasted when you never have to maintain anything, nor ever write anything big enough.

So while I'll say your idea does have merit, I think it can be done better. Don't just give them 1000 lines of someone else's code. Make them keep building and expanding the same program until the last year.

E.g., ok, in introductory programming they had to write some 100 line trivial program. But don't throw it away. When the next course comes along, give them the assignment to change or expand that original program.

E.g., if at some point you also get a computer graphics course, make them add a graphics module to that program. GUI programming? Sure, add a GUI to it. Database programming? Sure, make it save the data in a database. YACC? Ok, make them add a small scripting language to it. Different language? Make them port it to that language. Etc.

Make it a part of the grade to explain _what_ had to be changed and _why_.

Eventually it _will_ grow to be 1000 lines, and then it will grow even larger. And more importantly it'll be example of why code has to be readable and maintainable.

Re:Even more annoying...

The problem is that they try and teach you to write comments prematurely.

No, the problem is that they try and teach you to write code prematurely.

Document your application, requirements, constraints, and system interactions (what the engineer does). Then write the code (what the coder does).

What you will quickly learn is that it's better to be the engineer than the coder. What you'll realize is that the engineer is the client-side guy that figures out how to solve the challenge presented and the coder is the guy who can live in Manipal.

The computer scientist is another guy altogether, that sets the boundaries within which the engineer must work and provides many of the tools.

Somehow CS education has gotten horribly derailed, and asks students to combine the equivalents of electromagnetic theory, power system design, and basic home wiring in one curriculum. No wonder enrollments are plummeting - nobody knows what a CS major is or should do.

here's some Pretty Evil Shit - Re:Even more annoyi

Here is an example of some Pretty Evil Shit:
I want to laugh when I read it.
Some of it is funny.
Some of it is just scary.
The human mind can be a freakishly messed up thing.
http://mindprod.com/unmaindocumentation.html [mindprod.com]
It is part of a larger essay about writting crappy code.
Anybody that even comes close to software development
should check it out.

--- begin excerpts ---
Avoid Documenting the "Obvious" : : If, for example, you were
writing an airline reservation system, make sure there are at
least 25 places in the code that need to be modified if you were
to add another airline. Never document where they are. People who
come after you have no business modifying your code without
thoroughly understanding every line of it.

Units of Measure : : Never document the units of measure of any
variable, input, output or parameter. e.g. feet, metres, cartons.
This is not so important in bean counting, but it is very important
in engineering work.

As a corollary, never document the units of measure of any conversion
constants, or how the values were derived.

It is mild cheating, but very effective, to salt the code with some
incorrect units of measure in the comments.

If you are feeling particularly malicious, make up your own unit of
measure; name it after yourself or some obscure person and never
define it. If somebody challenges you, tell them you did so that
you could use integer rather than floating point arithmetic.

On the Proper Use of Design Documents : : When implementing a very
complicated algorithm, use the classic software engineering principles
of doing a sound design before beginning coding. Write an extremely
detailed design document that describes each step in a very complicated
algorithm. The more detailed this document is, the better.

In fact, the design doc should break the algorithm down into a hierarchy
of structured steps, described in a hierarchy of auto-numbered individual
paragraphs in the document. Use headings at least 5 deep. Make sure that
when you are done, you have broken the structure down so completely that
there are over 500 such auto-numbered paragraphs.

For example, one paragraph might be: (this is a real example)

1.2.4.6.3.13 - Display all impacts for activity where selected
mitigations can apply (short pseudocode omitted).

then... (and this is the kicker) when you write the code, for each of these paragraphs
you write a corresponding global function named:

Act1_2_4_6_3_13()

Do not document these functions. After all, that's what the
design document is for!

Since the design doc is auto-numbered, it will be extremely difficult
to keep it up to date with changes in the code (because the function
names, of course, are static, not auto-numbered.) This isn't a problem
for you because you will not try to keep the document up to date.
In fact, do everything you can to destroy all traces of the document.

Those who come after you should only be able to find one or two
contradictory, early drafts of the design document hidden on some
dusty shelving in the back room near the dead 286 computers.
--- end excerpts ---

Re:Even more annoying...

As a freshman I had a professor who kept giving me shit about not having enough comments, so my next program looked something like this: ...
a=5; //assign integer variable 'a' a value of 5
b=2; //assign integer variable 'b' a value of 2
print(a+b); //print to the console the sum of integer variable 'a' and integer variable 'b' ...

and so on, for about 200 lines. Worthless commenting? Sure, and childish too... but it was amusing and I never got docked for insufficient commenting again :)

Re:Even more annoying...

I just ripped this comment out of our code today: // close the file
closeFile();

Re:Even more annoying...

At work, we are not allowed to use comments in the code.

Allowing comments would "encourage coders to use clever tricks" according to the technical director.

Re:Even more annoying...

So tell us, since you have an inside view:

When is Longhorn actually coming out?

Gotta document that code...

From the Summary:

...I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized. Who's right?

You are. No question.

I have a saying I like to use when people (usually managers) try to persuade me to take the quick/cheap way out:


"Any time/money you save by cheaping out now, you'll wind up having to pay back twice over on the back end."

I've yet to see this maxim disproved, and it's just as applicable to coding as it is to anything else. Your colleagues are certainly correct when they state that the code must be well organized, but this simply isn't enough. If you don't put in the necessary time (minimal, really) to properly document your code, you'll wind up spending a lot of time trying to figure out just what you did and why. Also, even if you can remember exactly what your code is all about, the guy that comes after you probably won't...proper documentation is professional courtesy. I suppose they'll learn after they spend a few hours puzzling over a piece of old code (that's how I learned...:P ). Sooner or later, not documenting properly will bite them in the ass.

Re:Gotta document that code...

The canonical form of your maxim is "If you don't have time to do it right the first time, when will you find time to do it again?". The correlary is: "The problem with quick and dirty is that dirty remains long after quick is forgotten."

Re:Gotta document that code...

I actually agree with you though -- as long as the indent character in question is a tab. People who want to indent with spaces need their heads examined.

There'