|An Example of Poor Commenting Practice|
Why do so many people dislike writing? Because we are talking about writing and it isn't just source code comments. Many people (not only students!) will go out of their way to avoid natural language** writing, or will throw something together and spend minimal time making it comprehensible to others. If writing was taken more seriously, then perhaps articles, white papers, grant applications, reports, presentations wouldn't be procrastinated to the last moment such that "there wasn't time" to create kick-butt effective prose. If you have ever served as an NSF panel reviewer or for that matter a peer reviewer for ... well, anything... we feel each others pain.
**Natural language refers to languages such as English, French, Arabic, etc.
The idea that writing code and writing natural language have parallels is not new, but there has not been significant pedagogical research delving into the comparisons. There is much literature on teaching writing which is read by those who teach in departments such as English or Literature. There is a somewhat sparse literature in the computing education community about parallels between developing source code and natural language prose.
Good source code comments take thought and consideration just as good articles and reports do.
As far as I know there is no literature evaluating the similarities and differences between code commenting and natural language writing*** There are many possible reasons, such as the possibility that there aren't that many people who are pedagogical experts in both coding and natural language writing.
***If you know of any literature on the topic, if you have written any, please let us all know!
Meanwhile, let's toss out some thoughts to grease the cognitive wheels, shall we?
Natural language involves using words from a spoken language. Source code comments involve use of words from a spoken language. What are the similarities between a well constructed natural language sentence and a well constructed source code comment?
Natural language writing involves developing a logical narrative (in most cases). Source code comments clarify a logical narrative derived from the source code. What procedural lessons can be gleaned from the extensive literature on structuring logical essays and applied to source code comment development?
Students who like to write code often go out of their way to shortcut or altogether avoid writing comments. Students who like to write code often go out of their way to shortcut or altogether avoid writing papers, essays, etc. Students who have never seen a line of code often go out of their way to shortcut or altogether avoid writing papers, essays, etc. Motivation motivation - what leads to someone developing a healthy respect for a well written article and how can we apply the same psychological principles to source code commenting?
While I was teaching a computer science course at UT Austin I took advantage of a grant funded initiative, provided by the university writing center, to spread pedagogical best practices in integrating writing across the curriculum. I learned there is an enormous body of literature detailing effective strategies for teaching and learning writing. Equally important, it became clear to me that Coding is a lot like Writing...er, Coding is Writing.
Now I would add: Source Code Commenting is Writing.
After you get over the blindingly simple obviousness of that statement, think about the potential implications for the challenging task of encouraging programming language learners to produce more and higher quality source code comments.
I'm wondering how often pedagogical writing professionals hang out with pedagogical computing professionals. If they do, do they talk shop? What about comparing notes on pedagogical writing strategy? They ("They" being the non-computing members of the conversation) have many decades (centuries!) of experience to draw upon and share. I suspect there is an opportunity as well for knowledge transfer from computing to natural language writing. We share many of the same challenges (improving: motivation, quality, quantity, process, evaluation techniques, perceived value).
It might take some time to become comfortable with the different cultures and to develop common communication. That's nothing new for interdisciplinary computing buffs. Let's start the conversation.
*Comments in this post are my own creations and do not represent the official views of the COMTOR project or its team members!