Comments on IT Gears - Serving The Hacker Culture: Why programmers don't want to comment code

It's a good idea to comment our code especially fo...

2007-01-25T06:17:00.000+02:00

It's a good idea to comment our code especially for crowded functions, even with only several words. Better do it, than to sorry when you're trying to read your last year's code.

As a few people have mentioned, comments get out o...

2007-01-15T20:29:00.000+02:00

As a few people have mentioned, comments get out of sync. Clear, well-written tests (preferable written via TDD) make better documentation, because they are forced to stay in sync with the code. As a side benefit, testable code is generally also well-factored and readable.

You still need comments for one situation: to describe WHY your code does something. If your comments are describing WHAT your code does, you probably have room to extract a well-named method or make a similar enhancement to the readability of your code.

Documentation is like sex: When it's good - it's ...

2007-01-10T19:35:00.000+02:00

Documentation is like sex:

When it's good - it's out of this world...

When it's bad, it's better than nothing...

"A true Klingon warrior never comment the source" ...

2007-01-10T17:04:00.000+02:00

"A true Klingon warrior never comment the source"

Only seems to be a joke...

In an attempt to dispel the "I don't need to comme...

2007-01-10T14:32:00.000+02:00

In an attempt to dispel the "I don't need to comment my code since if the code is written clearly enough it should describe itself" theory, I present the following:

Definition 1.1

The purpose of code comments is to present intent.

Definition 1.2

A software defect is a deviation from intent. This definition does not make a distinction between implicit (i.e. expected but not defined in a requirement) and explicit (i.e. defined in a requirement) intent.

Theorem 1.1

Code is incapable of sufficiently presenting desired intent.

Proof I will provide an indirect proof of Theorem 1.1 by assuming "code is capable of sufficiently presenting desired intent" and obtaining a contradition. Choose a section of code that contains defects. By Definition 1.2 this section of code does not correctly describe the intent. QED

Notice that Theorem 1.1 contains the word desired. This is necessary to distinguish between the intent that a section of code with defects presents and the intent that is required. Also notice that Theorem 1.1 contains the word sufficiently. Later entries will expound on this in more depth but for now it will suffice to say that code utilizing crafty programming may obfuscate intent.

I do acknowledge that for those who use the "I don't need to comment my code since if the code is written clearly enough it should describe itself" to mean "I'm too cool / talented / whatever to comment" or to cover for "I'm too lazy to comment" that my argument will have fallen on deaf ears.

I have written extensively about comments in my blog at http://www.realityinteractive.com/rgrzywinski/. Just search for "comment".

I do a lot of code reviews, and from my experience...

2007-01-10T09:51:00.000+02:00

I do a lot of code reviews, and from my experience elegant code is self documenting - and I always try to refactor the code to make it self-explaining. there are a lot of good tricks to do it: short and focused functions/methods/classes with logical names, using variables in a smaller, focused scope, again naming them to reflect their intention. so the code itself is not a problem if it is written with that in mind.

I found that introspection and "intelligent code helpers" in java and c# actually caused people to stop reading comments and documentation in the last few years - they just type in the dot and expect to guess the correct method from the list which IDE offers.

So, as much as I'm in favor of writing good comments annd API documentation, if the method and parameter names are not self-documenting, there will be a lot of problems. Look at Swing in Java - the threading model is clearly documented in code, on the Net, explained in many books, but one of the biggest complaints about it has it's roots in the misuse of the thread model.

In short, documentation is good, but if the code is not self-explaining, and if it's easier to misuse the API then to use it correctly, programmers did not do their job.

"Self documenting code" is a trap. Some people thi...

2007-01-10T09:00:00.000+02:00

"Self documenting code" is a trap. Some people think that they make the code "self documenting" by omitting comments (which becomes true by doing so) - faulty logic, but mostly caused by a distorted perception what is clear for the original programmer and what is clear for all programmers.

Comments are mandatory in two situations: To document an interface (javadoc, etc.) and to document intrinsic behavior that makes the code work. Intrisic behavior is the exploit of side effect are any specific domain knowledge that went into the code.

A rule of thumb: If the comment is longer than the code, it is either redundant or the code needs rework, trying to be too clever is not smart. Also excessivly long comments might hint that the programmer didn't understand the problem and thus described what the code should do and he didn't manage to implement properly.

Code-reviews are a good occasion to validate comments, so if there is management so there are code-reviews, thus management cares (inadvertly perhaps)

Like Kirubakaran said... Comments on how code wo...

2007-01-10T07:42:00.000+02:00

Like Kirubakaran said...

Comments on how code works gets out of sync with the code.

Here is the best way imho:

Put header blocks around functions/classes/methods to explain use, input/output.

All "comments" then go into the code repository systems on commit/updates.

And when I say comments I don't mean explaining what the code does (that is clear from reading the code).

Comments should explain the INTENT of the code, the reason behind it.

Thus looking at a file's log history one can easily figure out what was the logic behind each change and how to modify or tweak it for the next requirement.

tribui

It's hard to set one rule about commenting that ap...

2007-01-10T07:25:00.000+02:00

It's hard to set one rule about commenting that applies to all situations. I generally try to write self-documenting code, but I put comments in where I think it would help the reader. Anything that might be perceived by a reader as astonishing or unintuitive I will decorate with a comment. Of course I try desperately to avoid writing clever or unintuitive code, because if the code is as clear as the comment would be, then I don't really need the comment, do I?

Generally I'll put comments above classes to describe the responsibility of the class, because this helps me think about the single responsibility principle. If I'm using the word "and" a lot in the description of the responsibility, perhaps I should have more than one abstraction.

Documentation does describe what the author thinks...

2007-01-10T04:41:00.000+02:00

Documentation does describe what the author thinks the code will do, but more importantly, it describes what he or she wants it to do. This makes it easier to spot where someone made a mistake.

When setting out to create a class or method, I personally find it useful to comment for everything I intend to do. I then write the code around the comments. Often I just delete them, but in other cases, it serves me well to leave some there.

Comments are especially useful when working in a framework you had no part in planning or creating. "Why did they use this when they could have used that?" You don't know unless there's a comment there. It doesn't mean the comment is necessarily correct, but at least it gives you a sense of what the author had in mind.

Yes, good code is it's own documentation. Because ...

2007-01-09T20:10:00.000+02:00

Yes, good code is it's own documentation. Because I don't document, I take extra care of choosing the right function/variable names, or even rewrite less readable code.

Documentation obfuscates code, it describes what the author thinks the code will do, and not that what really happens at runtime.

Only exceptions for documentation:
- Some explanation in front of a function, or on top of a module, on how to use the code.
- When code is intended to look like a bug, like an exploit, bug workaround or some undocumented language feature.

i don't comment or comment on a very high level co...

2007-01-09T19:51:00.000+02:00

i don't comment or comment on a very high level coz it is a pain to keep the comment in sync with the code. (ie. code update => updating comment too).

worse than 'no comments' wud b 'outdated comments'.