Team 4

Team 4 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!

Team Members (Name, Affiliation)

 * Michael (George Mason University)
 * Pete (The College of New Jersey)

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.

Not very useful to people who havent seen this code before.
 * http://fxr.watson.org/fxr/source/alphapc/sd53c8xx.c?v=PLAN9#L558

Good legalspeak. Maybe good for a lawyer. Not sure how this would be particularly useful to the ordinary reviewer
 * http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/java/org/apache/tomcat/util/IntrospectionUtils.java (line addJarsFromClassPath)

Comments dont explain the code at all. Do these programmers know what documentation means?
 * http://lxr.linux.no/#linux+v2.6.32/sound/last.c

Grammatical mistakes. This leads to further ambiguity.
 * http://lxr.linux.no/#linux+v2.6.32/arch/ia64/kernel/unaligned.c#L1403

Too wordy and misses the point.
 * http://fxr.watson.org/fxr/source/pc/etherelnk3.c?v=PLAN9#L991

Summary Questions
How do you define good comments and best commenting practices? Comments for each block of code. Comments above each function. Good comments are grammatically correct.

What documentation do you require from your students? We require that they document the date, author, class, section, purpose of that file .. We require that they specify the test data.

What strategies do you recommend to your students?

1) Comments should be as long as necessary without making the code ambiguous.

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 even room for this in the curriculum?

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=

Best Practices and 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?