Thoughts On Comments

A follow-up to a viral rant about code commenting, this post synthesizes community reactions and explores nuanced perspectives on when and how to write comments. Key topics include the debate over whether API docs (Javadoc, XML docs) count as comments, the false dichotomy between clean code and comments, a strawman proposal for a team commenting schema, and the social dynamics that affect comment quality. The author argues that clean code and good comments are complementary, that 'public' is a poor criterion for deciding what to document, and that writing skill is a learnable professional requirement.