Team 3

Team 3 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)

 * Sonal Dekhane (Georgia Gwinnett College)
 * Evelyn Brannock (Georgia Gwinnett 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.


 * http://lxr.linux.no/#linux+v2.6.32/drivers/acpi/acpica/evevent.c#L178

To the point and sufficient. The only thing we would have added is the datatype of the returned variable (STATUS)

Too wordy and too informal. Seems like "slang".
 * http://lxr.linux.no/#linux+v2.6.32/fs/xfs/xfs_mount.c#L2448

Lack of comments.
 * http://lxr.linux.no/#linux+v2.6.32/arch/x86/kernel/check.c#L100

License information available, but no description of the program and what it accomplishes. Should at least have: author information, program name, date, etc.
 * http://svn.apache.org/viewvc/httpd/httpd/trunk/server/vhost.c?revision=883860&view=markup (line 72)

Understandable. Explains the logic and warns those that are going to maintain the program to pay special attention to this module.
 * http://fxr.watson.org/fxr/source/port/dev.c?v=PLAN9#L216

Summary Questions
How do you define good comments and best commenting practices? Provide coding standards in a document form, then discuss the importance of each standard. Teach by example. Assign a percent of the total score to comments. A good comment should explain what the code accomplishes and how and does so in a succinct manner.

What documentation do you require from your students? Comments within the program.

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

Technical Software Project Commenting Guidelines

 * 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?