Coding Without Comments

http://www.codinghorror.com/blog/archives/001150.html

by ajbatac • 18 years ago

39 57 18 years ago

newt0311• 18 years ago

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.

procyon2• 18 years ago

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• 18 years ago

You mean:

  display_error unless valid_input

right?

comatose_kid• 18 years ago

Code without comments is better than code with outdated comments - this happens quite frequently.

ajross3• 18 years ago

Amen. Comments lie. This happens all the time. Programmers who try to maintain code by reference to the comments will get it wrong. You have to debug the code. Comments, at most, should be a guide to what happens where.

axod• 18 years ago

It depends on how well you write your code.

Also I think in general hackers should learn to read code. To reverse engineer. To understand what is going on without comments. Then when you do have some comments, it's a bonus (Or just even more confusing and contradictory).

rw• 18 years ago

You can write a provable theorem as a stream of symbols from mathematical logic, instead of prose. But, do you really want to read the result? Code can be made clearer through abstraction, certainly, but comments are a domain specific language for helping humans understand computer programs.

stcredzero2• 18 years ago

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

There are differing degrees to which this is true. Different languages had different design motivations. Smalltalk was specifically designed to be readable by humans. By grade school aged humans, actually! In the Smalltalk community, most regard comments as a "Code Smell."

mynameishere• 18 years ago

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

spydez• 18 years ago

My favorite comment that I've personally written:

    // Here there be magic. See datasheet for details; they explain it 
    // almost as well as I just did.

(followed by ~10 lines of math chock full of magic numbers.)

jgrahamc• 18 years ago

I maintained a piece of 250,000 line C code that had one comment in it (apart from copyright notices):

/* bad code */

To this day I do not know if this was a comment on the quality of the code that came after it, or if the developer was reprimanding the code.

gruseom4• 18 years ago

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.

cconstantine2• 18 years ago

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.

icey• 18 years ago

You don't have to know the right answer to know if the answer you've chosen isn't the optimal one.

While I'm sure it'd be nice to know all of the answers all the time, some of us mere mortals can continue to try to notify other people that extra attention should be paid to the code following those comments.

Hexstream• 18 years ago

I'm a perfectionist, and sometimes the only way I can make progress in my project is to do it the hacky way while documenting the promise to return later to fix it into a comment in the style of: "Lazy shortcut."

Sometimes doing it The Right Way would necessitate a big refactoring of the supporting code or learning a concept in more depth and I can't afford all that overhead (which might break flow also).

Also, sometimes a far-reaching refactoring might be carried out in stages over a number of hours or days and to go from where you are to The Right Thing you'll have to pass through a number of less-than-optimal stages. But I always find it easier and faster to use an incremental approach where I accept suboptimal solutions, most of which will be quickly overwritten anyway than trying to do The Right Thing all at once.

marijn• 18 years ago

Nonsense. Often your code will be ugly because some API in other code is broken or missing (see a lot of JavaScript), or doing something the right way is too slow or complicated, and you don't happen to have enough time to make a research project out of it. So then you add a self-deprecating comment to provide a little joy in the existence of the poor schmuck who will have to maintain your mess. Everybody wins. Kinda.

DanielBMarkham• 18 years ago

One of the most insightful things I've read here all week.

Sometimes I think I should make a macro out of //HACK:

culley• 18 years ago

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?

procyon2• 18 years ago

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• 18 years ago

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

jacobbijani• 18 years ago

Yeah, sometimes if I'm doing a complex logic block I will just put the conditionals in and fill them in with a short description of what will be there. Generally, since I've already written them I just leave the comments in after I fill the real code in.

I've noticed that my Javascript is usually very readable and doesn't require commenting for the most part. I think using MooTools has a lot to do with it, those libraries all encourage good naming practices.

hs2• 18 years ago

as time goes, you need less comments

dous• 18 years ago

as time goes, people tend to write less comments

hs2• 18 years ago

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')

nradov2• 18 years ago

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.

ajross3• 18 years ago

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.

nradov2• 18 years ago

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.

halo• 18 years ago

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.

noonespecial• 18 years ago

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• 18 years ago

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).

stcredzero2• 18 years ago

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!

silentbicycle2• 18 years ago

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?

gruseom4• 18 years ago

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.

maxwell• 18 years ago

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• 18 years ago

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

hernan7• 18 years ago

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...

silentbicycle2• 18 years ago

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.

Coding Without Comments

Related Stories