Team 2

Team 2 Workspace
Feel free to edit this page as you need to. If you're unfamiliar with mediawiki's syntax, please consult the User's Guide for information on using the wiki software or the workshop moderators. That being said, you need little fancy formatting -- the content is more important to capture. Feel free to make liberal use of the "Show preview" button!

Code Magicians

 * Dr. McLovin (Humboldt State University)
 * Jen (Oregon State University)
 * Tebring (Collin College)

Exercise 1: Assessing Real Comments
Please take a look at the comments at these links and assess them as you would a piece of student documentation. Write your feedback below each comment link directly in the wiki.

* Bad - doesn't tell us anything * Medium - we don't know about the field though, so it's a little vague * Medium - it's a little too detailed, and looks like automatically generated comments * Too many acronyms, and which OSes require this? * Perfect. Gives parameters and definitions of terms.
 * http://fxr.watson.org/fxr/source/mtx/clock.c?v=PLAN9#L36
 * http://fxr.watson.org/fxr/source/pc/etherelnk3.c?v=PLAN9#L1018
 * http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/java/org/apache/tomcat/util/http/MimeHeaders.java
 * http://lxr.linux.no/#linux+v2.6.32/arch/x86/include/asm/xen/interface.h#L76
 * http://lxr.linux.no/#linux+v2.6.32/mm/oom_kill.c#L54

Summary Questions
How do you define good comments and best commenting practices? * Explains difficult code, and block comments before methods are helpful. What documentation do you require from your students? * (Jen and Z) As a student, we were required to use JavaDocs in a java course (format comments in a certain way, and it automatically creates an html page for comments) * (Jen and Z) In beginning CS courses, we were required to comment. Some profs required specific style, and some just wanted comments in general. * (Jen) As a TA in a data structures course, comments and style are 10% * In grad classes, comments aren't really emphasized What strategies do you recommend to your students?

Exercise 2: Ideas for Student Assignments

 * Have students "dogfood" comments from classmates: in one assignment or exercise, have them write a component that is used by another classmate in the next assignment
 * Have them read OpenSSH, OpenBSD, FreeBSD, NetBSD code
 * One way is to supply developers or students with two versions of a file that are identical except for the presence of comments, and then ask them to:
 * modify a data construct
 * modify a function
 * add a new data construct
 * add a new function
 * Ask students to write down 15 adjectives for code (broken, fixed, good, bad, poor, borked, dumb, elegant, fast, awesome...) and then grep for these strings in source comments

Exercise 3: Discussion Questions

 * How do commenting practices vary across languages (e.g., functional vs. procedural languages vs. scripting languages)
 * What are the global principles for documenting source code?
 * What kind of mechanisms might an automated grading system contain? What are the limitations of such a system?
 * How do we measure the utility of comments? Hypothesis: comments are most useful when someone (e.g., student, developer) can report that a comment helped them understand a line of code, an error or system status condition, or code idiom. Or when the comment enables the developer to construct a new line of code more quickly.
 * How do we measure this improvement?
 * Is there room for this in the curriculum?

Technical Software Project Commenting Resources

 * Google Android:
 * http://source.android.com/submit-patches/code-style-guide#javadoc
 * http://source.android.com/submit-patches/code-style-guide
 * Linux kernel: http://lxr.linux.no/linux+v2.6.32/Documentation/CodingStyle#L425
 * Apache: http://httpd.apache.org/dev/styleguide.html
 * OpenBSD: http://www.openbsd.org/cgi-bin/man.cgi?query=style&sektion=9&apropos=0&manpath=OpenBSD+Current&arch=

Related Work

 * How to Comment Computer Programs
 * Top Best Practices to Consider (Microsoft)
 * Successful Strategies for Commenting Code
 * The Fine Art of Commenting (pdf)
 * MSDN's Using Comments Effectively
 * Comments are More Important than Code by Jef Raskin (ACMQueue)
 * The Hows and Whys of Commenting (CProgramming.com)
 * HotComments: How to Make Program Comments More Useful? (pdf)

Exit Questions
How can we use this website to promote disaster stories, success stories, strategies for education?

Is there an existing commenting tool, formatting / prettyprint tool you find valuable or useful?