Most programmers I’ve worked with can write some code within minutes of a discussion but stall when they’re asked to comment or to vocalise what they’re doing a

Most programmers I’ve worked with can write some code within minutes of a discussion but stall when they’re asked to comment or to vocalise what they’re doing and why. They believe the reason is that they are working at such an abstract level that it’s not easy to put into words until some higher-level concepts have been coded. Of course, at that stage, comments are not added either. Discussing the code for commenting at this stage often elicits a response which results in throwaway comments or another writer’s block. Everyone loses. My personal solution has been to approach code documentation as programming in one’s native language, or as is often done, in English. Learning to comment is given the same importance as learning to code. Comment maintenance is given the same priority as code maintenance. Explaining the actual function and expectations by comment is the essential part of writing code that expresses the functionality. Comments are given similar weight as code. Comment design is considered at an early stage. And comment maintenance is equally as important as code maintenance. Why do we talk about coding rockstars but don’t we talk about commenting rockstars? This isn’t anti-agile or anti any methodology if it’s presented as an integral and essential part of the task. Often, when mentoring such processes, the act of commenting liberates insights that may have only appeared during failed product testing. Of course, learning to comment effectively is learning to communicate effectively. Metrics for effectiveness are often elusive and people are rarely paid for lines-of-comments, so this is always a hard sell, unless it’s understandable to be a core coding activity. We see the same thing in related areas, like logging. Unless you need to solve a problem with the help of accurate logging data, you don’t see the need or utility of logging anything. As with comments and code, logging also needs consideration and maintenance. Learn to code Learn to comment Learn to log These mantra won’t come from above, so need to be learned and understood.