 |
| 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!
I am not sure that writing source code comments is as straightforward as it is made out to be. To write a comment, one has to first know what the purpose of the comment is. For a beginning programmer, that is something to hard to understand. I am not sure we teach that. I certainly haven't seen any programming text books explain what the comments are for. Secondly, writing a comment also requires a level of abstraction, to be able to summarize the function, to be able to appreciate what is essential and what is inessential. I am not sure we teach that well either.
ReplyDeleteInstead of asking students to comment source code, it may be better idea to ask them to write a report describing their program. That way, they write a separate document, which is completely text, and the students can try to make it look like the very many text documents they have read. They will then start wondering what should go into the report: specification? design? user interface? protocols? data structures? algorithms? testing methods?
In the UK, it is common practice to make all final year undergraduate students do a substantial project and write a report on it. We provide considerable guidance to them on how to write the report and the majority of them do a good job.
Most students' experience with writing (unfortunately) is in the form of forced five-paragraph essays, book reports, reader responses/journals, and exam questions. Yuk! Who actually finds this fun and interesting? (I know a few do, but they are the exception rather than the rule.) I think this mindset of drudgery really turns people off of writing. Sitting down to write something, even if it's code comments, likely triggers the emotions of frustration, boredom, and even insecurity if students think they aren't "good writers". Forcing students to write comments only piles on the drudgery.
ReplyDeleteHow many students sign up with excitement to learn how to play an instrument because they enjoy music, only to be turned off from music by doing mindless five-finger practice drills day in and day out? A few people will do the drills and and move forward, but in a massive blow to music education and the lifejoy of appreciating music, most students drop out and never sign up again. I think one can make a similar argument for writing and CS. The rub is, you have to practice to get better, but practicing isn't fun -- at least the way it is currently done and has been done for many years.
However, communicating one's ideas, including technical concepts, to others is a very important skill to learn as it reinforces analytical thinking and problem solving. Are there more interesting ways to do this? I turn to agile software development and see how it's done there. I emphasize agile because traditional software development is often a documentation-driven process and from my experience no one wants to write or read these documents. I highly doubt anyone wrote Facebook, twitter, or any iPhone app by sitting down and writing a specification document, then a design document, then pseudocode, then comments. So what do I find in terms of writing today?
- Software packages are documented via websites, wikis, and FAQs, all of which do contain lots of writing, often in narrative form.
- Tutorials that show other programmers how to use the API or configure the system for their own needs.
- Blog entries that detail how-to, lessons learned, personal frustrations and workarounds.
- Videos of tech talks, screen sharing sessions, podcasts. One has to plan, outline, and write to a detailed enough level to speak from.
I'm going to try it in my lab this fall, but I bet if I assigned students to one of these methods to communicate their design, there will not be that trigger of "oh, no, I have to write?!". It's a "head fake" because the focus will be on producing something interesting like a website or a video, but in reality, they are taking the steps to get them to the end goal of analytical thinking and iterative refinement (plan, produce, revise, learn/evolve) and there's no doubt that there will be writing involved. And when I do the big reveal at the end to tell them that they were writing all along, I hope it builds some confidence in the students and starts to de-fuse that "oh no" that even struck me when I was a student.
Your focus on interdisciplinary is something that really speaks to me and I will carry forward in my teaching. There is only one nature/world, and it's only human divisions of convenience that break apart subjects. Why does it have to be coding versus writing? Analytical thinking requires whatever it takes: sketching, writing, our reasoning/logic, creativity, our emotions. And the expression can take many forms as well, often in combination with each other: illustration, code, narrative, animation, and so on. Computing is a whole-brain effort - it's an art, science, and craft, all rolled into one and that is the beauty I want to help my students to find and see. It's a tragedy that students are just bleeding out of our field because they got caught up in the five-finger practice drills and haven't had an opportunity to see how mind-blowingly amazing it really is.