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