With respect to writing prose there's a saying, "Don't write to be understood; write so that you can't possibly be misunderstood."
Which is the goal of writing code, where you have to explain _exactly_ what you mean to the computer. Which is hard work. Hard enough that there's a likely cognitive bias -- the code must be self-explanatory since you spent so much time getting it right, especially if it came out (you feel) rather elegantly. In that frame of mind, there's likely to be some fatigue or irritation associated with going on to write comments, when "obviously" it already "speaks for itself". Writing code is relatively easier in one respect, because the "audience" is small and well-defined: the computer/environment. When it comes to writing code, and comments, for other programmers, now the audience becomes more diverse. What's the background and experience of the other programmers? How much do you explain vs. assume? One audience member to keep in mind is a future version of you. You, coming back months or years later. It can be an interesting and education experience to discover how understandable your own code -- and the comments -- are. Personally, I think the amount and type of comments varies by programming language and style. In heavily OO C++ I found the class design plus good names tended to make things more self-documenting; maybe with some strategy hint like "// this is the Observer pattern". In Java, the language itself is fairly verbose and sometimes feels like "comments by other means". :) Whereas in non-OO C, or in Racket, it might be that documenting the key data structures heavily is the sweet spot -- if that's clear, then the code manipulating them doesn't need so many blow-by-blow comments. Maybe just the occassional explanation of something like approximating 1/√x using 0x5f3759df. [1] Browsing Racket's source code, I've often wished for just a _few_ more comments. Especially a paragraph at the top of a module or complicated function, giving some hint why it exists, what's generally going on. However, I guess the deeper issue is that older parts of Racket use older idioms -- more Scheme-influenced, and/or the way you had to code it before Racket got X (and/or the way you still have to code it because that portion of Racket can't require X). [1] http://blog.quenta.org/2012/09/0x5f3759df.html ____________________ Racket Users list: http://lists.racket-lang.org/users