After years of struggling with the question of how to write "good comments" I've come up with a solution I'm currently happy with. The main problem with commen

After years of struggling with the question of how to write "good comments" I've come up with a solution I'm currently happy with. The main problem with comments is they make code less readable because they interrupt the flow of code-reading and thus code-understanding. But now, I write all my multiline comments in this style: /*------------------------------------------------- This is a comment */ In the IDE I am using (WebStorm) there are keyboard shortcuts for collapsing and expanding sections of code. For comment-sections like above it collapses them into: /*--------------------------------------------- ... */ What this does is it turns a code-reading distraction (the original multi-line comment) into .. a SINGLE LINE SEPARATOR. Single-line separators do not negatively disrupt the flow of reading the code. In fact they actually help code-reading by dividing the program into semantically coherent code-sections separated by what looks like a simple horizontal line. I'm no longer very concerned about out-of-date comments, I accept them as fact of life. They are ok as long as they don't impact my code-reading negatively. I don't need to ponder: Is this comment too long? It is not when it is collapsed. And comments will still contain much useful information. If I don't understand why some section of code is there or is written the way it is, I can expand the comments around it and maybe I find some helpful information there. Often I do. I do wish the IDE would offer more support for this style of commenting. It would be great if all multi-line comments would be collapsed by default. I haven't figured out if that is possible in my IDE. I do know how to "collapse all sections" which is what I frequently do. It is a good way to start reading a code-file anyway. So, the trick is really simple: Start every multi-line comment with a line that consists of a line of dashes.