Hacker News Reader

Regarding comments, I really liked a technique Martin Fowler talked about in Refactoring.

Whenever he feels the need to comment, he extracts the commented block into a new method and gives it a name that explains the purpose - instead of the comments.

The result is code cut into small self-explaining blocks that reads pretty much like a sentence.

I tried to follow it these last weeks and IMO it works great.

Instead of a comment - use a function name.

View on HN

Yeah, I followed that advice at one point. But I find in practice a plain English comment can be much more helpful than a function name. For example, from the code I linked:

# Check too many lines. Count number of lines without a comment.

If I were to turn that into a function name I would either have one long ass function name or (more likely) I would cut out several words and lose a lot of readability and clarity.

countLinesSinceComment() too long for you?

I think it's a bit too long, yes. I prefer around 10-15 characters for function names. Also, you've lost a lot of readability with that camelCase. Also, the "Check too many lines." part wasn't superfluous -- I had a separate check for too many total lines before I count the number of lines without a comment -- and that part of the comment has been lost.

Reply on news.ycombinator.com