Team 6

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

 * Phyllis Tedford (Texas A&M University - Corpus Christi)
 * Tina Johnson(Midwestern State University - Wichita Falls, TX)

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.

Appears relevant to the code; not sure precedence is the best descriptor. Description needs more detail. Version needs date, revision number, and/or what was revised. Good description, but including pre- and post-conditions would make it better. Comments, comments, who stole the comments? Humerous, but useless.
 * http://svn.apache.org/viewvc/httpd/httpd/trunk/server/util_mutex.c?revision=894361&view=markup (line 334)
 * http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/java/org/apache/tomcat/util/http/BaseRequest.java
 * http://lxr.linux.no/linux+v2.6.32/kernel/fork.c#L965
 * http://lxr.linux.no/linux+v2.6.32/arch/x86/include/asm/desc.h#L64
 * http://lxr.linux.no/linux+v2.6.32/net/rds/tcp_recv.c#L299

Summary Questions
How do you define good comments and best commenting practices?
 * Meaningful descriptions of actions taking place (especially in "cryptic" code).
 * Comments written for others who might read the code.

What documentation do you require from your students?
 * Program prologue for all programs.
 * Significant embedded comments as needed.
 * For functions, prologues that include purpose, pre-conditions, and post-conditions.
 * Provide a style guide for both commenting and coding style they're required to follow.

What strategies do you recommend to your students?
 * Use program and function prologues to help design the program/solution.
 * Provide sample programs with appropriate comments and in the correct style; suggest they use those as guidelines.

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?