

Does anyone use comments any more? - robomartin

Maybe it's just me.  I am old school.  I also have to come back to projects months, and in a few cases, over a year after having written the code.  I was taught to comment and comment profusely.  And that's what I do.<p>Every function, method, variable or property has a comment.  Even within methods, clear explanations of everything that goes on is everywhere in my code.  The logic of a loop, the reasoning behind a conditional, the setting of flags and some variables.  In some cases the commenting is a mini-story of how the program flows and why certain things have to be done.  An easy-to-follow plain-text explanation of the code.<p>Yes, this takes time and work but it has always proven to be well worth the effort.<p>I've cloned a few GitHub projects and, I have to say, I am absolutely amazed when I look at the source files.  Project after project without comments.  Not one.  Just a pile of code.  Not only does this require more work to understand what the author was thinking or why he or she took a specific approach, but I would imagine that the code is also harder to maintain and evolve as the author and others loose touch with it for months or more.<p>Is this what they are teaching in school these days?  Damn the documentation, just write code and make it work?<p>I, for one, will not accept anyone working for me taking this approach.  Code is expensive to produce and it must be well documented for others to maintain, support and evolve.
======
nkurz
_I, for one, will not accept anyone working for me taking this approach. Code
is expensive to produce and it must be well documented for others to maintain,
support and evolve._

You might be right, but you also might be focusing on the wrong thing. There
is a case to be made that the goal should be clarity, and comments should be
reserved for the cases where the code itself cannot be made clearer. Steve
McConnell expresses this particularly well:

[http://www.scribd.com/doc/95398523/McConnell-Code-
Complete-C...](http://www.scribd.com/doc/95398523/McConnell-Code-Complete-
Chapter-32-Self-Documenting-Code)

The whole chapter is a gem, and it's hard to find a pull-quote that does it
justice. It's probably the single piece of writing that most changed my
attitude about programming. But if you'd like a starting point, your position
sounds a lot like a character in his opening allegory at line 177:

 _"I want to suggest a commenting standard for our projects," Thrasymachus
said. "Some of our programmers barely comment their code, and everyone knows
that code without comments is unreadable."_

~~~
robomartin
I didn't have time to read the entire thing. I scanned it quickly and have to
say that I don't think I disagree with the recommendations of that paper. In
general terms comments should not describe the mechanics of the code "looping
through all available names" but rather the intent "Find the user name".

That comments get out of sync with code is a fact. That they stay out of sync
is inexcusable. What I will generally do is to fully test and debug a chunk of
code and then go back and annotate. I sometimes have a "Go comment the code"
item in my to-do list and will spend time here and there cleaning-up and
clarifying comments. The other interesting thing that can happen when
commenting this way is that you can find issues with the code or identify
refactoring opportunities.

It's like sitting down to explain what the code is doing to another capable
programmer as opposes to a 12 year old who is just starting to learn how to
program. Maybe that's the best way to put it. What do you say to an experience
programmer if you had to do a code review and explain your code? That should
go in the comments.

If a method or subroutine is absolutely trivial then you say "This finds the
average of the voltages across these four inputs".

If, on the other hand, the routine is more complex, you have to describe the
overall intent "this calculates the values of the missing pixels" and then
dive within the module to explain some of the specific techniques being used
"Polyphase FIR filter to interpolate image data for missing color samples" or
"Bounds-limited adder to clip FIR filter data to legal image data range".

In other words, you don't explain every line of code but rather functional
chunks that make it easier to navigate it and understand what is being done at
a macro level and why.

Again, my peeve is with projects that have files upon files with not a single
comment. I don't expect a book.

------
btilly
I personally find code with profuse comments harder to maintain and evolve
over time than code without. Because you have to maintain the comments as well
as the code, and never know when you can believe the comments. (General rule
of thumb, if in doubt, do not believe the comments.)

 _IF_ you have only high quality people, and _IF_ you have high quality code
reviews, _THEN_ it is possible for comments to become maintainable, valuable,
etc. I personally have only worked in one software organization where this was
true.

------
rsaarelm
Schools are terrible at the craft of software style stuff. The one time they
did teach me about comments, they seemed to insist on something like seen in
this story: <http://thecodelesscode.com/case/39>

I think there might actually be an old-school element here. Coding up to the
80s or the early 90s tended to be about squeezing the absolute most capability
you can from the machine. Clarity and conciseness probably took the back seat
to optimization hacks, so writing the comment to describe the original intent
of the code actually was vital.

Peter Norvig's old Lisp programming book has a nice illustration on how the
programming style in Lisp has evolved from the 70s to the book's 1992:
[http://books.google.com/books?id=QzGuHnDhvZIC&lpg=PP1...](http://books.google.com/books?id=QzGuHnDhvZIC&lpg=PP1&dq=paradigms%20of%20artificial%20intelligence&pg=PA30)

SICP also had the "programs must be written for people to read, and only
incidentally for machines to execute" quip, and also notes "In this book we
don't use many comments; we try to make our programs self-documenting by using
descriptive names."

Since the 90s, programmers have had a bit more breathing room, and the idea to
actually write the code itself so that it will concisely describe what it's
doing when read by a competent programmer has become much easier. You still
want to document nontrivial interfaces, tricky things from the application
problem domain and problem workarounds in the code, but the actual business-
as-usual code tends to be readable and idiomatic enough that you don't need to
comment every function, method and variable. Most can be inferred well enough
from context.

------
boos3y
As a recent college graduate, I can tell you that they still teach the comment
everything everywhere method, and in fact for most of our programming
projects, documentation was at least 20% of the grade. I professionally, do
not comment, but instead, write "clean code" that can be understood simply by
reading it. Anything complicated I comment, but usually that means I need to
refactor and rethink my approach.

I highly recommend this book: [http://www.amazon.com/Clean-Code-Handbook-
Software-Craftsman...](http://www.amazon.com/Clean-Code-Handbook-Software-
Craftsmanship/dp/0132350882) as it changed my life when it comes to software
development. I have a real problem with commenting everywhere as most of the
time you'll find a lot of public String getName() with like a comment of
//Gets the name, uh, durr its name is get name! If you create concise methods
with one general purpose you can create very readable code. Definitely check
the book out, it is a very good read.

------
mds101
This comment was originally posted by shasty ut for some reason has since been
deaded. I thought it was worth reposting:

Over commenting is a bad practice. Comments should be reserved for code which
is difficult to understand no matter how well it can be written.

Forcing a developer to constantly shift between the english language and a
programming language takes up precious screen space and insults the developer
by constantly making her switch gears.

Inline comments are the worst abused. After that method doc for the purposes
of supposed documentation.

A well named class in a stable framework needs no documentation as long as its
interface is intuitive.

Chances are you are interacting with really bad systems and want some help. If
the code is that bad, I doubt the developers comments would be much better.

No comments is the best if you can get away with it and have a self
documenting set of interfaces.

~~~
robomartin
I disagree. This isn't about interfaces. This is about their inner workings
and the reasoning behind some of the decisions or techniques being made.

You talk about over-commenting. I am talking about no comments whatsoever, not
even to document methods or subroutines. I cloned this one project that was
loaded with methods not used anywhere. In fact, it had included the SBJson
framework and it was being used in a method that never got called. The issue
came up because it collided with my own use of SBJson on my project and I
wanted to figure out what to do about it. It turns out that I could just
delete the entire thing and it did not affect the code at all.

I'll give you another example. I have not programmed in Forth in a long time.
Maybe fifteen years. However, I do have tons of Forth code that I wrote back
then for various projects. All of it is very well documented. I have no doubt
that, fifteen years later, I could grab that code and be back in the swing of
things in no time at all. I wouldn't have to read through the code in detail
and go through the process of building stack images in my head to figure out
what is going on. Without comments code libraries like that become
impenetrable black boxes.

I could say the same about LISP. I haven't touched it in ages. I wrote tons of
utilities and at least one major framework (one year dev time) for a variant
called AutoLISP (runs inside AutoCAD). Again, tons of comments which would
allow me to jump right in and know exactly what is going on.

It should go without saying that trivial stuff does not require comments. As
an hypothetical example, a loop that searches an array (or whatever) for a
specific match doesn't need line-by-line comments. What I might do here is,
again, hypothetical, just before the "for" statement throw-in a comment that
says something like "Look for CRC code match in packet data". With that simple
line anyone reading the code knows what the intent was. I can read that code
five years later and know exactly what it does without having to read
backwards and forwards through the code to figure out what each variable might
be, where they come from, what they are loaded with, what the intent might be,
etc.

I also find it invaluable to document state machines (particularly for
hardware --FPGA-- designs). If you take something like a custom DDR3 SDRAM
controller state machine, well, it isn't a trivial thing to read through and
figure out what it is doing. Well-authored comments can turn something that
would take hours-upon-hours to comprehend into an easy read.

I have seen the value of good comments and code documentation many times over
during my career. Keep in mind that I am not making a comparison between
sparse comments and writing a book.

~~~
sirmarksalot
How about you break out your "Look for CRC code match in packet data" loop
into a boolean function called "PacketContainsCRCCode"? The rule of thumb that
I learned early on, and that I try to apply, is that comments should answer
the question "why," not "what." "What" is easily answered by naming your
methods (and variables, should you be forced to use them).

I know what you're getting at. There's nothing worse than reading a 50-line
function with no comments. But the real WTF isn't the lack of comments - it's
having a 50-line function in the first place (or 8000 lines for that matter).
Having lots of comments is a code smell - it indicates poorly factored code.
Next time you need to write a comment explaining what a piece of code is
doing, try writing a function instead, with a name that says what it's doing,
and see where that takes you.

I highly recommend Misko Hevery's "Clean Code Talks" on YouTube. They're part
of the Google Tech Talks series, and they will blow your mind if you let them.

------
caw
Since I started writing Perl I absolutely started adding more comments. I make
sure that I add a comment with sample input for my regexes, particularly if
they're complex.

The Regex comments make all the difference, because I can easily check if my
sample inputs that I wrote the regex against have changed. I'm also reminded
of what I'm trying to get, instead of trying to figure out "Okay, I have a
$host, $ip, ..."

------
greenmanmax
Hi, (robo)Martin, My opinion on comments is, that they are extremely useful
for functions, classes (f.e. javadoc). It is essential to know, what a part of
code does. In the function body, I think it is much more important to use
meaningful variable names. I mean: Do I really have to comment a variable like
"numberOfUsers" with a statement "The number of users"?

~~~
robomartin
Of course, variable names need to be really descriptive. And, no, they don't
each need a comment. Here's an example, in a recent app I had to slice an
image based on a given number of rows and columns. The variables were named:

    
    
      int image_rows;
      int image_columns;
    

The actual code, with comment, went something like this:

    
    
      // These variables will determine how the image is sliced.
      // They are bounds-limited in code to max values imposed by hardware and 
      // defined in configuration_settings.h
      int image_rows;
      int image_columns;
    

A year from now I won't need to read far into the code to understand what they
do.

------
drothlis
_I've cloned a few GitHub projects and, I have to say, I am absolutely amazed
when I look at the source files. Project after project without comments._

I wish people would add a one-line comment to the top of every source file
saying what it's for. ONE LINE is all I ask.

------
scott_meade
<http://tomdoc.org/> makes comments the perfect bridge between "documentation"
and "code"

------
joe_the_user
I use comments far less than I once did. I spend more time writing self-
documenting code.

Over time, I had the experience of mine and other people's comments generally
being out of sync with the meaning of the code. Further, extremely complex
code is too complex to fully document in the code and easy code should require
no documentation. There's a middle ground but its much less than everything.

The time I once spent on comments I now spend on picking function and variable
names as well as writing tests and asserts. Tests and Asserts are nice since
if they stop being true, they force you to change them, unlike comments which
can stay stale with no repercussions.

This isn't saying I write no comments. I write comments but a comment is
intended for something unusual. That's good because that means it will get
read.

------
jdbernard
I completely agree with you. When I write code, the actual code only captures
a small fragment of the total mental model that is my solution to the problem
at hand. There is so much information about the problem that is _not_ captured
purely in code that a maintainer would need to know to make well-informed
decisions about the system going forward. I have been fortunate to be in the
position of handing off my work to a colleague. Knowing I had left a well-
documented system behind was a great satisfaction.

The only time commenting becomes difficult for me is if I am in a team where I
know I will be the only one maintaining good comments. It takes no effort to
update comments as you code but if I am the only one doing it then it becomes
a problem.

------
macford
are you working on an open project that involves team? Then IMHO you need
comments, but most of the time I develop website and app by myself and I don't
need much comment for explaining, only as reference as to what the code
section is, and no one has complained about it yet

~~~
dagw
Maybe it's just me, but on several occasions I've gone back to (uncommented)
code I'd written several month or years ago, and thought "what the hell is
going on here? Who wrote this shit?" Those time I really wish past me had
taken a few seconds to write out exactly why he had solved that particular
problem in that particular way, despite how obvious it no doubt seemed at the
time. There are few things more annoying than finding some 'ugly' code, fixing
it, having a bunch of stuff subtly break and then finally remember that there
was a very good reason why you originally wrote the code the way you did. If
only I'd left a comment of two for future me, much time and anguish could be
saved.

~~~
kenbot
Sounds to me like tests could have helped your code far more than any comments
would have.

~~~
dagw
Some stuff, especially stuff connected to performance or memory usage, is very
tricky to write tests for. Doubly so if it is only a problem on certain
hardware.

~~~
kenbot
That's certainly true. I'd argue though, that most code is in a position where
good naming and tests provide sufficient clarity, without requiring free-text
comments.

~~~
dagw
Tests can only tell you what some piece code is supposed to do, not why its
doing it the way its doing. Why do you choose to define this particular
constant to this particular value, why are you using that particular data
structure, why are you rolling your own version of a certain function rather
than using the one supplied in the library you are using, why are you using
that seemingly round about way to get to that particular result?

There are lots and lots of ways to write a function that passes a test, I want
to know if there is a reason why you chose the approach you used.

