Youry's Blog

Youry's Blog

Why don’t people like to comment their code? (some comments from ACM SIGCSE for the SE students)

leave a comment »

Very interesting post by Kendrick Hang (13 July 2012):

“Ok, so I’m going to come at this from a completely different point of view. I’m going to argue against commenting code. Code that is poorly written or that is difficult to understand requires comments to explain what it does. Code that is well written is self documenting and can be understood clearly just by reading the code.

Code never lies, comments can and inevitably do. When code is compiled, run, and traced through a debugger, there is no arguing how it works. Comments however can be (1) interpreted in different ways because natural language can be ambiguous (whereas the code is written in a formal programming language), (2) incorrect over time because they are not updated when the code is updated, or (3) just plain wrong and/or written poorly because a developer added them in a slapdash manner just to say he or she has finished commenting the code after finishing “the hard part” which is getting the program to work.

From my personal experience as a software engineer, my team and I have spent days (take 3 engineers * engineering labor rate per hour * 32 hours = a *boatload* of money) chasing the wrong thing because we trusted the existing comments in the codebase instead of the code itself. Writing good, meaningful, clear, appropriate comments is a skill that takes time to learn and understand. Comments need to explain the “why” or the design decision and not the “how” as the code already expresses the mechanism/process. Really, I’d rather focus energy on getting the team to write code that is clear and self documenting so we don’t have to rely on the comments to understand what is going on.

I am not alone in this assessment though. Check out Jeff Atwood’s (co-founder of, the premier programming Q&A site on the web) writeup on coding without comments:

and also his writeup on pseudocode:

Another place to read more about this point of view is in Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall PTR. 2008. Robert C. Martin is also known as “Uncle Bob”, who leads up the Software Craftsmanship movement. A quote from his book: “The proper use of comments is to compensate for our failure to express yourself in code. Note that I used the word failure. I meant it. Comments are always failures.”

I did come to this point of view over time. When I first took AP Computer Science (back when it was still in Pascal), I commented the heck out of my code and I actually was kind of proud that everything was documented, pre- and post-conditions, a description for every variable, an explanation for every loop. I believed everything my teacher taught me. When I took Advanced Software Development Methods in college, it was my professor who introduced this radical idea to me that comments were often “bad” with respect to software maintainability. It was when I got to industry when I realized that software is not a 100-line program you submit and forget. What I inherited in my first job was a 100,000+ lines of Perl/CGI scripts that was five years worth of software evolution, features, fixes, etc. and the first thing I realized was that there was about 8,000-10,000 lines of out-of-date, incorrect, and meaningless comments in there just making the clutter worse (// i is an index for the loop, // sorry about the kludge, or // j. smith — TO DO). Been the same way in every other codebase I’ve worked with.

Despite my contrary opinion here on code comments, I do believe we can agree that the end goal is to help students learn how to communicate an idea, from the abstract mental model of the problem to the concrete implementation of it, clearly so that not only one can understand one’s own work, but so others can understand it as well. And as the Perl motto goes, TIMTOWTDI: there is more than one way to do it.”

I think he has a very good sense and if our students could write a clear and good code we really don’t need to much comments. But question is what is more easy to write: a good code or to write good comments to the “not good” code? A good code is much more important, but how many students could write a good code?


Again very good example from Dennis J Frailey on 13 July 2012 (I copy full his message):

Dennis J Frailey • “This makes less and less sense the larger your software system. It’s like arguing that you don’t need blueprints or house/building plans [think software architecture and design] or notes on which circuit applies to which part of the building (in your circuit breaker box) [think comments] because a well constructed building can easily be understood. This may work for 1800’s vintage log cabins but with a large, modern building this just isn’t practical. And of course even with a small, modern building there are things you cannot readily determine without the plans or the notes in the breaker box. (Try to figure out where the plumbing lines go in your slab foundation.)
This same thing applies to software. Anyone who has been involved in maintenance of a large software system will tell you that to understand the
system only by looking at un-commented code is an overwhelming task and things like information hiding may just make it harder. Of course the
actual construction may deviate from the design and comments, but the more effective approach is first to understand the plans and comments and then verify that they match the actual construction. It also helps to invest in doing good designs and notes in the first place and in updating the design/documentation when changes are made. In short, the way we build software today is too often akin to the way people build housing in undeveloped countries. It can be inexpensive and effective but it won’t scale up well.”


New interesting comment from David Casperson posted on 12 July 12:

“No one doubts that a history essay or English essay is meant to communicate to fellow human beings.” Students … “don’t doubt that the purpose of an essay is to communicate to a human reader.”

“When we switch to mathematics and mathematical proofs, undergraduates get confused by the difficulty of calculation and proof, and they often mistakenly think that the purpose of written mathematics is to document the correctness of a calculation, rather than to communicate with their peers.
There are differences between the language of mathematics and the language of literature. The former requires precision and correctness to such an extent that it becomes a great skill to capture the precision and correctness and still remember that one is primarily engaged in natural language communication with other human beings.”
“They think that they are communicating intent to a computer. Of course, in part, they are. Proofs need to be correct. Code needs to compile. But the whole mindset is wrong. Code should be thought of as being designed for human consumption, just like blue-prints, and legislation, and proofs, and RFCs, and a host of other technical communication. ” – Very good point of view. From myself I want to add that all 4th generation programming languages were invented for humans at the first, but then only for computers!!!

The full comment see on the provided link above.


She ” gives group projects, with each group working on a different assignment (database interface for a bank, web interface for a florist, etc.). The second part of the project is to extend the work of another group. They quickly learn the value of good documentation!” – very good idea. I think it’s necessary to try as well. Maybe we should have 1 group and several subgroups, but we need to have enough time for it.

“In my undergrad capstone course, they have to produce a requirements specification document and other materials similar to what a real-world vendor does. In addition, in all my classes I make them design the software on paper first (object model and data flow), then create object stubs in the IDE with documentation regarding the purpose, input and output of each method. Several students have told me that it helps keep them on track. They frequently go back to the diagrams. ” – I like it, but I found that many students don’t like design. We should try again.


“… the motivation for doing something is your own expectation in succeeding times the value of the task dividided by the delay in until you see the result and the impulsiveness of the individual. If we compare the two tasks programming (low-level design & implementation + debugging/testing) and writing/reviewing in terms of this, the following points sums up my experience in teaching students programming, design, testing etc. ”

“…  students can expect to succeed in designing and implementing something that works, due to the tool support, internet forums etc. In contrast, writing comments in the code or, for that matter, documenting something there is little support. ” – good point.

“… the value of writing code can be almost immediately visible, whereas the value of writing comments or documenting can be weeks, months or years awa and valuable to other people, not to themselves.” – We should give code evaluation immediately to the students during the project and give the same code immediately to the students for maintenance. (Youry)


One reason I have not seen mentioned, but which professional programmers tell me more often than not is that comments are just another thing to try to keep up to date and accurate as the code changes. Given the churn which some significant code undergoes during development, it is likely that comments placed at the start of development of that code either are very outdated by the time development is complete ( assuming development is ever complete) or have been changed a great deal.

Inaccurate comments are worse than no comments at all. Obvious comments ( for example, sets A to 6 ) are more trouble than they are worth. Good comments won’t be common until there are cheap tools that produce them automatically from the design, the requirements, and the source. Even when such tools are available, they are not widely used because they are considered cumbersome and slow.
Posted by Kenneth Magel


Ah, “professional programmers”. Is this what we are preparing our students to be? I personally prefer the term “professional software developers” because there’s so much more involved than programming, but I could argue that even that isn’t broad enough. We should be preparing people who understand computers (hardware and software) well enough to develop professional quality computer-based systems.
But let’s return to the term “professional programmers”. Unfortunately, too many take this to mean people who earn their living by programming. This is a broad sense of the term. But too many people earn their living by programming in a decidedly unprofessional way. They crank out code that is hard to maintain and support, not very reliable, and lacking many other desirable qualities. They are motivated by speed, style and cleverness, not by truly professional quality. I’m reminded of the quickly-built, attractive-on-the-surface housing that one often finds going up in low-income (and even high income) neighborhoods. Ten years later there are problems galore and the builder is long gone. (Did you ever wonder why US standard home owner warranties last only 10 years when the houses ought to last a lot longer than that?)

A narrower definition of “professional” software developer is one who develops professional quality software, which means they utilize the appropriate methods, tools practices and techniques to achieve the level of quality suitable for the job at hand. High quality may not be needed for handheld device apps, web pages, and a lot of software used by a lot of companies – but it is pretty important for software that has a long lifetime and must be supported and maintained; and of course it is essential for safety-critical, security-critical, and other applications where the consequences of failure may be serious.

So to get back to Kenneth’s point, we need to determine what we are preparing our students to be. If we want to educate professional software developers in the narrower sense described above, we should perhaps ask some genuine professional software developers to stop by for a guest lecture now and then. It might be particularly insightful for students to ponder what quality means for software, what safety issues might be software related, etc. Someone working in, say, the nuclear power industry (or transportation or defense or medical applications or even financial applications) might be able to bring some good, realistic examples for the students to think about. [By the way, recent alumni and industrial advisory board members are often truly professional software developers. Or check out the ACM and IEEE-CS lectureship lists for people with the right kind of background.]
Posted by Dennis J Frailey


I thought I’d do a little research so I contacted two individuals whom I consider to be professionals in the field of software development. One is involved with sustainment (maintenance) on US Navy fighter aircraft. The other is in the US Air force and is responsible for evaluating software safety on various products. This is not the developer but, rather, the person who is brought in to evaluate the software produced by others. (Typically this position is held by a very experienced, senior software developer.) Neither wanted to be named because they need approvals for such things. But here is a synopsis based on their comments. I note a few new wrinkles (such as the inaccessibility of the design information in some cases).

Navy SW Sustainment person:
Where comments are most important is with large software systems where you simply cannot understand the whole thing. I’m frankly amazed that anyone questions this because if it weren’t for comments our job would be impossible. The need for comments is even more acute now that people do object oriented designs. This is because the design tools they used to develop the designs in the first place are often either no longer available or require expensive software that we don’t have. A prime example is Rational Rose. Many critical projects were designed in Rose back in the 1990’s and now it is no longer supported. Those of us in sustainment are in a different organization from the development group and we don’t have the software needed to examine the design. We have to rely on the comments in the code. Moreover, object oriented designs sometimes result in code that is very hard to understand. For example, information hiding is a nice concept in theory but, in practice, it sometimes means those of us trying to modify the software cannot figure out what we need to know.

Even when we can see the design, we don’t trust it. One of the big problems with object oriented design is that people invent their own unique notations instead of following accepted standards. I must have seen over a hundred unique variants of UML, each of which someone thought was clever. But from my perspective, the variant just confuses things. When I get the software, perhaps 5 years later, the developers are long gone and I can’t make head nor tail of some of their “clever” variants. And, by the way, we always update the comments when we update the code because we trust the code more than the design (in those cases when we have access to the design). It’s easy to update the code as part of a maintenance activity. It’s a lot more work to update the design to be consistent with the modifications, so it often doesn’t happen.

Air Force safety evaluator:
A key to safe software is clarity of design and code. My job is to review the code and make sure it has been written in accordance with various standards and principles. Many modern languages are far from intuitive. For example, C++ code can be very hard to follow. So we insist on good comments from suppliers of software that must be certified for safety because it is essential for our understanding of the code.
Posted by Dennis J Frailey


Written by youryblog

July 4, 2012 at 11:13 PM

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: