Hacker News new | past | comments | ask | show | jobs | submit login

I couldn't disagree with this more strongly--giving somebody a blob of code (no matter how elegant) is a recipe for disaster.

Let's assume good comments--not useless, lying, or broken ones. I won't contest that bad comments are at least as bad as useless, as you doubt would not contest that bad code is at least as bad as useless.

When I read a comment, I parse it directly. When I read code, no matter how neat it is, I often trigger a twitch of "How would I rewrite this?", which itself gets in the way of understanding.

The more code there is, the harder it is going to be to digest at first glance, and if your codebase could be adequately described by a single page of text I would wonder why I need to work on it instead of rewriting it entirely.

Hint: if you only have one page of docs, and especially if you have no test suite, I cannot work on the code in a meaningful way safely.

If you don't value safety, if you don't value engineering, then by all means omit comments. It's just a crutch for people who can't see the code man.

I might also point out that that same philosophy implies that we should just stick with assembly. Especially if you use any language with dynamic types/duck typing (Ruby, Javascript, etc.) seeing "at a glance" what exactly is the proper form of data to pass into and out of function can be hard. Documentation here helps.

EDIT:

Note also that commenting in libraries, or in mathematical or geometric routines, can be really helpful. The code doesn't lie, sure, but if you aren't experienced/schooled/clever enough to recognize what is going on it won't help you.

A great example of this is the fast inverse square root hack:

http://en.wikipedia.org/wiki/Fast_inverse_square_root

This has great examples of both inscrutable (but honest and short!) code, and shitty commenting.




The problem domain of the source code dictates the value of the comments. If the code is highly algorithmic or data structure driven its more useful to include a pointer to a book / paper rather than littering the code with comments which will never do as good a job at exposition as a book / paper.

On the other hand arcane business logic needs to be documented because there is no way to recreate that from a mental model.


Generally I would agree with this--the problem is that citing papers/books/sites can result in brittle, broken external references. Ideally both a brief explanation and a link to the source material would be helpful.


I do value safety and engineering - in my mind, an ideal deliverable would be the source code, an automated test suite, and a 1-page document explaining the overall design of the code.

Comments don't provide safety - tests do. Comments are not good engineering - well designed code that is easy to reason about and follow is.


Automated > Manual

Proof > Tests == Documentation > Correct Comments > Nothing > Incorrect Comments

None of these things are mutually exclusive, and all non-trivial code should ship with a combination (obviously excluding "incorrect comments"). I think inline comments should be relatively unneeded, and should only describe why you did something in an unusual or non-intuitive way. Otherwise, your code should require few comments, because what it does should be obvious.

Regardless, you sure as hell better document and/or test your interfaces. The nice thing about tests is that they can automatically be verified for correctness; documentation and comments cannot.




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: