
Coding Without Comments - ajbatac
http://www.codinghorror.com/blog/archives/001150.html
======
mynameishere
My impression...as you become more experienced, your comments will tend more
towards confession and pleas for forgiveness...

    
    
      //XXX I don't know why this works
      ...
      //XXX Worst kludge of my life
      ...
      //FIXME this whole pile of crap needs re-written

~~~
gruseom
Comments like this seem cowardly to me. If you can do better, then do. If you
can't, write the best code you can and be enough of a man or woman to commit
what you did and not clutter it up with excuses.

~~~
cconstantine
In a perfect world those kinds of comments would never be written.
Unfortunately there are times when there simply isn't time to do it the Right
Way (tm).

In those times when you have to do it the Fast and Ugly (tm) way, it's nice to
make a comment that you really don't like the code. It adds some humor, and
lets the maintainer know that there is no emotional attachment to that section
of code.

~~~
gruseom
_there simply isn't time to do it the Right Way_

Of course, this is the first thing that everybody says. And since everybody
says it, everybody thinks it must be true. But my experience has been that if
you really want to do good work, it turns out not to be true (say) 80% of the
time. So the next time you find yourself making a mess because you believe you
"have to", you could try stopping and questioning that assumption. You might
surprise yourself. How do you think I learned this? Certainly not by following
what the majority of programmers believe.

Edit: Rather than using phrases like "the Right Way", I'd suggest toning
things down and looking for _a_ way. There are many ways. If you get in the
habit of thinking there's only one, and it's capitalized and trademarked, the
bar seems a lot higher than it really is.

~~~
DanHulton
Clearly you have never worked in a situation with a looming deadline.
Sometimes there is simply no time to clean things up, you just have to extend
from whatever code you have, no matter how ugly, because you aren't given the
go-ahead to spend the extra time cleaning.

~~~
gruseom
_Clearly you have never worked in a situation with a looming deadline._

I've made my living writing code for the last 12 years. How likely do you
really think that is?

There's a deep streak of passivity among a lot of programmers. That's part of
why they (we) tend to be downtrodden. The belief that one must do shoddy work
unless "given the go-ahead" to do good work is as much a part of the problem
as anything else.

~~~
gnaritas
Exactly, stop seeking permission and just do good work all the time. It takes
how long it takes and those people making up deadlines will be forced to
adjust to the speed at which you work. They don't _know_ whether you're doing
it right or wrong or clean or ugly, they don't know what the fuck you do
anyway, so do it how you like to please yourself.

------
nradov
He missed the distinction between in-line comments and API comments. Pretty
much all skilled developers would agree that in-line comments should be
minimized, and used only when necessary to explain the reasoning behind a
particular design, or to clarify a complex section that can't be refactored.
But for API functions which you intend other developers to use as black boxes,
you need to provide extensive comments clearly explaining the purpose, inputs,
outputs, error conditions, and maybe even some sample code.

~~~
ajross
That's documentation, not comments. Nothing hurts code readability more than
huge chunks of markup (markup!) getting in the way of the code you need to
read to maintain. Javadocxygenwhatever generates pretty web pages, but leads
to write-only source files.

~~~
nradov
I appreciate the readability problem, but what would you propose as an
alternative? In my experience, combining the code and documentation in a
single file makes it much more likely that developers actually will update the
documentation. Besides, any decent editor will hide the documentation if you
don't want to see it.

~~~
ajross
How about abstraction? Draw a clean line between the API you're trying to
document and the code that implements it, and make sure that comments for
either don't cross-pollute. This is a good idea anyway.

I can't tell you how many automatically generated documentation trees I've
seen that are utterly worthless. Documentation of public interfaces gets mixed
in with usage notes on internal structures, and you don't know what you're
supposed to use.

------
culley
Not sure about you, but I learned to code by writing psuedo code.

I routinely start with comments that psuedo code my idea and then add the
sections of the code.

If I can't remember how everything is supposed to work while I'm writing it,
what hope does the intern 2 years from now have in adding a new feature?

~~~
procyon
if a code is changed comments need to change too! Too many times I have seen
out dated comments adding confusion to the code. If my code requires great
deal of explanation, I go back to my drawing board and redesign the logic.

~~~
dangoldin
Very applicable point. I keep on noticing this happen and I would prefer no
comments to outdated comments.

------
noonespecial
Those comments he doesn't like are often required by coding practices in a
team setting. Rightly so as there are often people of many different skill
levels working on the same code.

------
greyman
While it is true that when some idea can be expressed by descriptive variable
or function name, comment is not necessary.

But there are many places in the code, where it is highly desirable to explain
by plain words, why certain solution was adopted, that certain part is a bug
fix, or why some part of the code is counter-intuitive. I for one am much more
happier when my colleagues comment their code extensively.

To look at it from the opposite side: Is there any inherent problem with
having too much comments? (provided they are correct).

~~~
stcredzero
If you can't write intention revealing code, this often is a symptom! Most
often this means that there are implicit rules written into your code base.
90% of the time or more these should be factored out!

Also, another problem with too many comments: this is more stuff to maintain.
Chances are, the programmer already has enough to do!

------
silentbicycle
What about assertions? They work well as comments, but they're actually
_tested_ , and you know immediately if they go out of date.

You can decide one way or the other whether to compile them as no-ops in
releases, but it seems like a big improvement either way.

------
maxwell
To some extent it depends on your language. jQuery seems about right for that
kind of JavaScript.

<http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.js>

~~~
boucher
Actually, that seems like comment overkill to me. Almost every line has a
comment.

------
hernan7
If you document you need to keep the comments in sync with the code. If you
write self-documenting code, you need to keep the function names in sync with
the code. You just can't win...

------
silentbicycle
The worst comments are the ones that say, "this is awful, will fix later".

I try to datestamp my comments, but I've seen some of the above with dates
three years old. Why?

~~~
gruseom
I already commented on this so I guess it must be a bit of a hobbyhorse, but I
think I can answer your question. The comment really has nothing to do with
coming back and fixing it later. It has to do with alleviating a feeling of
guilt (or is that shame) about shoddy work. So the comment has served its
purpose and that is why it is there.

Once you make a point of never doing this, the psychological pressure has to
find another outlet, such as just fixing the code in the first place.

------
halo
It wasn't the point of the article I now feel smug about being able to
identify that Newton-Raphson implementation before reading the line below.

------
hs
as time goes, you need less comments

~~~
dous
as time goes, people tend to write less comments

~~~
hs
Most of the time I deleted my own comments after things become more obvious -
I hate 'moving parts' in my code

The trick is to highlight comments with bright & contrast fg/bg color combo
that hurts your eyes (it also serves to say 'hi i'm comment, i'm important,
but delete me when u understand me')

------
newt0311
I disagree. Code without comments will never be as understandable as code with
comments.

This is true because code is designed partly for computers while comments can
be written entirely for humans.

This is important because comments only have to be written once and maintained
occasionally while code without comments has to be reinterpreted every time it
is read.

~~~
procyon
Not quite! I think code can be written to make it self explanatory. With
appropriate variable, function names along with proper abstraction and
refactoring code can be read almost like a prose which eliminates need for
comments. At times comments are too annoying because they state the obvious or
they are not updated along with the code.

eg: code like this in ruby can explain itself very well!

display_error if not valid_input

Now I do understand that comments cannot be replaced entirely and sometimes it
is necessary to add notes to understand the code thus I prefer using comments
sparingly and avoid long headers on top of each file. Those headers with
author name, dates and other information is unnecessary if right tools are
used to maintain your project.

~~~
bkudria
You mean:

    
    
      display_error unless valid_input
    

right?

~~~
xlnt
I don't like "unless". Why do you? Every time I have to actually think about
what's happening, I change it to "if" so all the logic is actually written
visibly.

~~~
raganwald
I use "unless" in ordinary speech. Unless I'm talking with someone who
dislikes the word.

~~~
xlnt
I don't parse/think-about boolean logic like English.

~~~
raganwald
Then you probably won't be happy with languages like Perl and Ruby, DSLs, or
the "There is more than one way to do it" line of thinking some people have.

It's a big world out here, there's room for Spock and for Kirk.

~~~
xlnt
I love ruby, and use ruby at my job. I just don't write unless. Certainly
there is no cause for someone to say a statement is mistaken just because it
used if+not. Nor to guess that someone won't like ruby just because he doesn't
like unless.

~~~
raganwald
Saying someone is mistaken because they used "if not" instead of "unless"
doesn't align with my understanding either, as I tried to point out by listing
yet another way to write the same thing.

OTOH, you made a much more interesting statement than simply saying you didn't
like "unless," you took things into a discussion about programming languages
resembling vs. not resembling English.

Ruby has a bunch of lispy things that have nothing to do with English, but it
also has a bunch of Perl-inspired things that have a lot to do with expressing
logical ideas in English-y "prose."

If you can reconcile those two things, then yeah, you'll like all of Ruby. If
not, you'll probably find a subset that pleases you. So sure, I can see that
you might like the Ruby you use.

~~~
xlnt
You said you use "unless" in English as if that proved it was good to use it
in boolean logic too. It doesn't. For example, I am happy to use !, &&, and ||
in my code, even though they aren't English. The criterion for what makes good
code is different than what is good English.

My point was that I think an explicit not is clearer than unless in cases
sufficiently complex as to require stopping to think about it. If you're
trying to keep track of multiple negations, then having one be in a different
form than all the rest does not help. (And meanwhile, there is nothing wrong
with a habit of always using if).

~~~
raganwald
"The criterion for what makes good code is different than what is good
English."

In total, yes, but that does not mean that there are no things that work in
English that also happen to work in code.

Furthermore, it is difficult to generalize about this: some programming
languages are entirely unlike English and work very well, others attempt to be
like English and are terrible, while others attempt to be like English in some
ways and work.

And further to that, some parts of some programs attempt to be like English
and work well, while other parts of programs work well when nothing like
English.

Now while I understand bang, andand, and oror, they are a terrible legacy of
our C++ days. Bang is especially unforgiveable. If we must have a prefix
operator, what is wrong with ~, the actual standard symbol for negation?

;-)

p.s. This thread may seem to be a digression, but it seems quite pertinent to
an article that talks about writing code for readability.

~~~
demallien
What's the matter raganwald, jonesing for a blog post now that you've hung up
your blogging shoes? :-)

~~~
raganwald
Sadly, cutting out my blogorrhoea has no statistically significant effect on
my logorrhoea.

