Hacker News Reader

Comment by AstralStorm | Hacker News Reader

The code might be obvious, but if you don't include the reason why it exists it's a target for removal. And having too many of those makes either for garbage or hard decisions when refactoring.

Writing the rationale is the most important comment you must not skip.

And there would be links to design documentation so that it can be kept up to date. (For non-programmers.)

View on HN

Why it exists ought to be explained by the existence of a test.

This isn't always possible, but it's far more possible than many developers seem to think.

That just makes two things that need to be commented doesn't it?

When I read code I care about what the code is supposed to do and why it's supposed to do that.

There is code that passes the current tests and is logically sound but no longer fits the business requirements. Knowing that it was implemented to solve a certain use case helps the reader / reviewer see whether the code and the test still fit or if they should be updated.

The best comments I've come across comment the intention and any context that isn't immediately obvious from the function.

Your test should explain what it's testing. Via it's name or some other mechanism. Otherwise how do you know what's gone wrong when it fails?

That other mechanism is comments.

Does that explain why, though? It explains that it's there, and someone obviously wanted it to be, but it still doesn't get at the why. I've found that most of the logic I'm left scratching my head at is due to some business rules that there's no better way to deal with - even if a test exists for it I still can't figure out what the tests purpose was, other than to just verify that it's working.

Reply on news.ycombinator.com