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