Hacker News Reader

This readability requirement is a bit overrated. It's best to rely on comments and documentation so that you can rewrite something if you have to.

I see lots of Java that's written in a simple and direct manner, but that has no documentation/comments and where it's a pain to find the execution flow in between so many classes and layers (especially when there's dependency injection).

View on HN

> Especially when there's dependency injection

If it were just dependency injection it would be one thing but when you have all the opaque behavior that comes with a framework like Spring you get a bunch of spooky action at a distance code that can't be followed simply by traversing the call stack.

Couldn't disagree more. Comments should only ever be present to explain why a choice was made. Never what code is doing. If it needs to explain what the code does, the code needs to be rewritten.

Comments don't compile, so the only documentation of what code is doing guaranteed to be correct is the code itself.

Comments go beyond explaining why a choice was made, and this is usually not very useful information for a comment.

Really like comments for providing edge cases and information that can't be found by reading and understanding the code.

Reply on news.ycombinator.com