Hacker News Reader

Comment by cessor | Hacker News Reader

The author states:

"Most of the things programmers say about comments in code are excuses for not writing any comments at all"

This is true. Here is my excuse:

1. Follow all rules for writing good comments 2. Comment is now short, crisp and concise 3. Apply "Extract Function" refactoring, use comment as function name 4. Your comment is a compiled entity now 5. Write testcases for the function that explicitly explain corner cases and weird behavior 5. You have no comments in the code any more

This rule can be applied almost all the time, although it can be quite hard to use when global variables or wide scopes are used (e.g. 1000 line for-loops in C). Comments are either obvious or they're lying. Why would you write something that the compiler will ignore eventually?

View on HN

Comments are not to explain corner cases, but to explain why are you you doing what you are doing, what is your motivation. Why are you calling a system API with these strange parameters? Why do want to sort this table? Why are you lazy loading these data structures?

If a function fits into page, refactoring it into several tiny well named functions will give you an implementation where you can easily see what you are trying to do, but makes it difficult to see what you are actually doing, as you need to jump around between function implementations to read it. With a few good comments you'll get the best of both worlds, and you can now read both your implementation and your intentions with a single continous read.

First, you shouldn't hide information about corner cases and weird behavior in test cases. Do you read through test cases every time you use a new function? Neither does anyone else.

Comment-less code is not a virtue. Useful comments that describe the "why" (but not the "what" or "how") of code are a virtue.

Design decisions and reasons for why you wrote the code the way you did are hard to encapsulate in test cases. Describing the limitations of the obvious method which made you use a less obvious method is pretty instructive for the next person left scratching their head at your implementation.

> Why would you write something that the compiler will ignore eventually?

Because your real target for your code is not the compiler, it's your co-workers, who will have to go back and read and modify your code. Plus, they may not be able to contact you with questions about your code.

A single well written comment can save your co-workers from having to read a hundred lines of test code (and correspondingly, test code boilerplate). Why not give them that kindness?

> Comments are either obvious or they're lying.

This argument only applies to poor comments, which were not maintained alongside the code. If you just remember that the audience your code was written for is not the compiler, it makes more sense.

>>Because your real target for your code is not the compiler, it's your co-workers, who will have to go back and read and modify your code.

Your co-workers and your future self. :)

in rare cases: your customer

Your argument is not an argument against comments, it's against any kind of description.

Your code works just as well if you assigned each function a unique number starting from 'func0' - that's how code obfuscators or minifiers work.

Unless the act of shoving comments into function names makes the compiler type-check them, you are still writing something that the compiler will ignore eventually.

I think his argument is: "Comments is not a substitute for short functions and javadoc". That sounds extremely valid, imho.

If that was his argument I'd be happier with it. As described, his goal was to encode comments in the function name and describe caveats in test cases; none of those steps sound like 'write a javadoc'.

Javadoc and comments are both forms of code documentation. Perhaps we can generalise OP's point to the following:

"Most of the things programmers say about documentation of code are excuses for not writing any documentation at all"

I'm not going to use a library without documentation in favour of one that is documented. Above a certain minimum standard, it doesn't matter how 'clean' the code is if you don't understand why it exists. Cute naming simply doesn't make up for a lack of documentation, and avoiding documentation should be considered a cone of shame, not a badge of honour.

This for instace sort of agrees that just tests isn't good documentation http://programmers.stackexchange.com/questions/154615/are-un...

Reply on news.ycombinator.com