Team 5

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

 * Ivan Potier (McNeese State University)
 * Dijana Cvetanoska (McNeese State University)
 * Kevin Haywood (McNeese State University)

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.

The comments seem to be descriptive in a way that it explains why they added the code. I don't think it really explained what the code was doing which might be important.
 * http://svn.apache.org/viewvc/httpd/httpd/trunk/server/listen.c?revision=806010&view=markup (line 87...)

the format of the comment seemed useful, it says what the code does, then it says what needs to be done. the line 395 seems worthless.
 * http://lxr.linux.no/#linux+v2.6.32/arch/x86/pci/common.c#L395

not the most optimal way of commenting. why are they saying for now we assume something......
 * http://lxr.linux.no/#linux+v2.6.32/fs/ubifs/budget.c#L370

not helpful at all... very dumb
 * http://lxr.linux.no/#linux+v2.6.32/drivers/isdn/gigaset/i4l.c#L180

it appears that the comment is talking about a problem in the code and a workaround in making the code work. why dont they just fix the problem?
 * http://lxr.linux.no/#linux+v2.6.32/drivers/ps3/ps3stor_lib.c#L27

Summary Questions
How do you define good comments and best commenting practices? there should be a consistent format throughout code (ex. listing output, input, parameters, description, functionality, where its used) before all functions, classes...etc... brief and to a point consistent indention comments in ambiguous areas

What documentation do you require from your students? we have pretty much been taught what i explained above

What strategies do you recommend to your students? same thing

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?