Team 1

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

 * Tim (Sam Houston State University)
 * Barbara (Southwestern 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 comment itself seems to describe the logic of conditional test, but it lacks any reference to the overall context of the code.
 * http://svn.apache.org/viewvc/httpd/httpd/trunk/server/util_mutex.c?revision=894361&view=markup (line 334)

The comment describes when and why the function is being called in an appropriate fashion.
 * http://lxr.linux.no/#linux+v2.6.32/kernel/panic.c#L389

The comment attempts to explain what the code does; the first two paragraphs are clear, the third is awkwardly constructed grammatically, and is not clear.
 * http://lxr.linux.no/#linux+v2.6.32/arch/x86/include/asm/spinlock.h#L42

Needs to be more precise in describing the actions of the function being called.
 * http://lxr.linux.no/#linux+v2.6.32/net/rds/tcp_recv.c#L295


 * http://lxr.linux.no/#linux+v2.6.32/drivers/pci/probe.c#L1032

Might be appropriate for prototype code, but not in production. (Actually, even in that event, it should describe what needs to be changed in the future to make the code appropriate.)
 * http://fxr.watson.org/fxr/source/mtx/clock.c?v=PLAN9#L31

Summary Questions
How do you define good comments and best commenting practices?

Good comments should make the behavior of the code clear without having to read the actual code. Comments should be sufficient that if the author returned to the projects months later, s/he would get up to speed quickly, but a new reader would not get bogged down in the details and lose the big picture.

What documentation do you require from your students?

Every file needs a comment with author, date last modified, and purpose of the code module. Every function (method) needs to have a comment with any preconditions and postconditions. Comments must be grammatically correct (although not necessarily complete sentences.)

What strategies do you recommend to your students? Commenting everything not immediately obvious. Follow examples of good documentation provided by instructor. Comment before and while coding. (Not afterward!)

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

FrsiLV rpxdcjpykpwi, [url=http://pwfrtujeboqg.com/]pwfrtujeboqg[/url], [link=http://hgrusqpgtsnz.com/]hgrusqpgtsnz[/link], http://xfjjgnlnjzaq.com/

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?