tag:blogger.com,1999:blog-2682124344165339446.post742316354832007938..comments2024-02-05T18:31:35.119-08:00Comments on Interdisciplinary Computing Blog: Source Code Commenting is WritingLisa C. Kaczmarczykhttp://www.blogger.com/profile/00761462757785528055noreply@blogger.comBlogger2125tag:blogger.com,1999:blog-2682124344165339446.post-26119322024978855112012-07-13T23:11:28.188-07:002012-07-13T23:11:28.188-07:00Most students' experience with writing (unfort...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.<br /><br />How 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.<br /><br />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?<br /><br /> - Software packages are documented via websites, wikis, and FAQs, all of which do contain lots of writing, often in narrative form.<br /><br /> - Tutorials that show other programmers how to use the API or configure the system for their own needs.<br /><br /> - Blog entries that detail how-to, lessons learned, personal frustrations and workarounds.<br /><br /> - Videos of tech talks, screen sharing sessions, podcasts. One has to plan, outline, and write to a detailed enough level to speak from.<br /><br />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.<br /><br />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.Kendrickhttps://www.blogger.com/profile/04200481486976856094noreply@blogger.comtag:blogger.com,1999:blog-2682124344165339446.post-57945966192297787302012-07-03T00:07:40.416-07:002012-07-03T00:07:40.416-07:00I am not sure that writing source code comments is...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 <i>purpose</i> 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 <i>abstraction</i>, 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. <br /><br />Instead of asking students to comment source code, it may be better idea to ask them to write a <i>report</i> 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?<br /><br />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.Uday Reddyhttp://www.cs.bham.ac.uk/~udrnoreply@blogger.com