Hacker News Reader

Comment by threeseed | Hacker News Reader

Thank you so much for this article.

Just because a developer thinks their code is a gift from the gods and understandable by all doesn’t make it true.

Code is the what. Comments are the why. You can’t expect the developer’s intent to come out through the code alone.

Writing good comments is not necessarily easy task. When you're writing code, everything seems obvious. You can write obvious comments, but they won't help. I think that best comments would be written by someone who came later and had to understand the code from the scratch.

Or even just by yourself a little after you've written the code. When you yourself are trying to figure out how it all fits together exactly.

I do this:

#1 If anything in a pull request isn't blindingly obvious, ask a "why are we doing this here?" style question.

#2 Encourage all developers to do this on all pull requests.

#3 Get developers to answer those questions in the form of a pushed code comment rather than (or as well as) answering the comment. Make that an iron rule.

IMHO this gives the best comments. I'd usually discourage comments that don't come about like this.

>Code is the what. Comments are the why.

In general I'd prefer to see 'why' attached to behavioral tests.

When I am asking "why was it written this way?" 8 times out of 10 it's the actual desired behavior that I don't get, maybe 2 time out of 10 it's "why was it implemented this way" (and most of the time those are apologizing for hacks).

I’d argue if the why isn’t clear from code alone, then it’s the programming language’s or library API’s fault.

Until you have a better language or library, write comments but you should be striving to find better tools.

Which PL features could replace comments in natural language in your opinion?

LINQ in C# makes code very declarative, not only reducing the line count by half but also making it obvious what the code does. Code like persons.Where(x=>x.age>21).OrderBy(x=>x.Name).ToList(); doesn’t need a comment to spell out what it does, but imperative code might.

Being able to easily create types as needed gives not only compiler guarantees but also communicates exactly what sort of “id” or “name” you’re dealing with.

Generics separate orthogonal parts of logic, e.g. a List vs domain object. I remember the days when the domain objects would contain the “next” pointer. More generally any ability to separate aspects is hugely helpful. Eg: list<lazy<person>> is a lot easier to read than baking it all that in one object. Once done, you don’t have to have a section of code inside person that says “instantiate these fields lazily for performance”.

You’re asking the wrong question.

Better question: “What feature am I missing from my current PL or API that would mean I didn’t need this comment/documentation?”

Then strive to get that built.

For example a type system removes the need for an entire kind of method comment.

DSLs are excellent at this. Lombok removes the need for an entire kind of class comment.

Convention over configuration is great at this. Rails routes removes the need for an entire kind of comment.

Moving optimization’s into the compiler are good for this. Removing the need for an entire kind of comment.

Rust’s borrow checker removes the need for an entire kind of documentation around concurrency.

Every time a PL or library gets more advanced/ergonomic it removes the need for an entire kind of documentation.

Why shouldn’t we strive to take this to the limit, making better and better PLs and libraries till we need 0 documentation?

Reply on news.ycombinator.com