Follow us on Twitter at http://twitter.com/blogCACM
The Communications Web site, http://cacm.acm.org,
features more than a dozen bloggers in the BLOG@CACM
community. In each issue of Communications, we’ll publish
selected posts or excerpts.
commenting code, the arguments are
simplistic and general; comments are
necessary for a variety of reasons:
1. Not all programmers can write really obvious code. Beginning programmers are just happy to write a correct
program; they are still mastering the
craft. Even experienced programmers
write sloppy code. Programs are unique
like fingerprints, so judging whether
code is obvious is a subjective call.
2. It can be tedious to comment too
much, but some comments are like titles
and subtitles in articles; they guide, provide context, and convey overall meaning.
3. Comments are not just for code;
they can document important program
information such as author, date, license, and copyright details.
4.Some programming languages
are cryptic, like the Glass programming
language.Th is sample program (http://
a comment could convey its meaning.
5. Some companies require employees to comment their code. Google’s
programming style guides specify how
6. Specialized comments allow tools
like javadoc, JSDoc, and apiDoc to generate professional, thorough, and consistent documentation for programs.
7. Comments can be placeholders
for future work, a useful way to create an
outline for a large program. The Eclipse
Integrated Development Environment
(IDE) creates a TODO comment when it
generates a main method, a reminder to
add the starting code of a program.
Commenting may be tedious or overwhelming, but it is valuable in many situations. Even if you think you write obvious code, try reading your code months
or years later; will it still obvious to you,
or would you wish for comments?
A key characteristic of comments is with
respect to narration, as Ward Cunningham
has pointed out. It can be important to
distinguish what the code is *for*, not just
what it is, and what the key assumptions and
constraints might be. It is valuable to develop
a grasp for what the requirements are, and
code is rarely a substitute for that.
Dennis — That is a good point. There
are times when you just need a quick
overview of the code, without spending
time to trace through it. Comments help
here, assuming they are correct.
Why Code Comments
February 26, 2018
In computer science,
When you learn a new language, you
learn the syntax for a comment in that
language. Although the compiler or
interpreter ignores all comments in a
program, comments are valuable. However, there is a recent viewpoint that
commenting code is bad, and that you
should avoid all comments in your programs. In the 2013 article No Comment:
Why Commenting Code Is Still a Bad Idea,
Peter Vogel continued this discussion.
Those who believe commenting
code is a bad idea argue that comments
add unnecessary maintenance; when
code changes, you must also modify
comments to keep them in sync. They
argue it is the responsibility of the programmer to write really obvious code,
eliminating the need for comments. Although these are valid reasons to avoid
Commenting on Code,
Edwin Torres considers the enduring value of code comments,
while Walid Saba wonders if we have overreacted to
the knowledge acquisition bottleneck.
DOI: 10.1145/3193752 http://cacm.acm.org/blogs/blog-cacm