Skip to main content

Learning to Code: Comments Count

I like comments in computer programming source code. I've never been the programmer to claim, "My code doesn't need comments." Maybe it is because I've always worked on so many projects that I need comments to remind me what I was thinking when I entered the source code into the text editor. Most programmers end up in a similar situation. They look at a function and wonder, "Why did I do it this way?"

Tangent: I also like comments in my "human" writing projects. One of the sad consequences of moving to digital media is that we might lose all the little marginalia authors and editors leave on manuscript drafts. That thought, the desire to preserve my notes, is worthy of its own blog post — so watch for a post on writing software and notes.

Here are my rules for comments:

  • Source code files should begin with identifying comments and an update log.
  • Functions, subroutines, and blocks of code should have at least one descriptive comment.
  • Comments should be on their own lines, when possible, so they are easier to spot.
  • Comments should be concise and meaningful.
  • Cryptic comments are worse than uncommented code.

Computer languages have a variety of ways to mark comments. I assume each language's creator thought he or she had the best approach for indicating text was a comment. I like "!" because it "screams" that something is a comment (Fortran), but I also find /* comment */ quick and easy to type. If I were creating a language, I'd probably adopt "#" at the start of comment lines (Perl, PHP, Python, and Ruby).

Because this series of blog posts reports my attempts to learn Objective-C and Cocoa, the C and C++ comment styles are important to know. Before 1999, the only "official" C source code comment format was:
/* comment here */
/***************************************************
* A multi-line comment in C ends when the compiler *
* reaches the asterisk-slash pair. *
***************************************************/

/**
* Multi-line does not require asterisk overload.
* Keep comments short.
*/
I like C-style comments, but that's probably because I learned C in the 1980s and have never bothered to learn C++. When you use a coding convention for 20 years or so, it seems pretty natural. There's really no reason C-style comments are better than the C++ style now used in most C-family languages. The C++ style that is favored by many companies is:
// C++ style one-line comment.

// Special note:
// The C++ style can continue across lines \
with a backslash. Avoid this style.
Returning to my personal comment guidelines, program source code should begin with comments. If we look back to the Xcode template for a C program, it begins with comments similar to those I would add anyway. The Apple Xcode template isn't exactly what I would add, but it beats the lack of comments I've (not) seen too often.

Source code files should begin with identifying comments and an update log.
//
// main.c
// Hello World C
//
// Created by Scott Wyatt on 2013-04-04.
// Copyright (c) 2013 Tameri Publications. All rights reserved.
//
My personal style for the top of a code file is:
/**
* File: main.c
* Program [or Function, etc]: Hello World C
*
* Copyright (c) 2013 Tameri Publications.
*
* 2013-04-04 Created by CSW
* 2013-04-10 Expanded printf() examples
*
* TODO Add other output function examples
*
**/
In every Xcode project, there is a "main.c" or "main.m" source code file. That name doesn't tell a programmer much of anything. Yes, this is the "main()" function, but of what program? I add the program's or function's full name on the next line.

My second rule is:

  • Functions, subroutines, and blocks of code should have at least one descriptive comment.

If you look at the template code, Apple does include one comment at the start of the main() function:
int main(int argc, const char * argv[])
{

// insert code here...
printf("Hello, World!\n");

}
Obviously, replace "insert code here…" with a meaningful comment. I've had programmers argue that they select "self-commenting" names for functions and variables. That's nice, but I never assume a function's name is enough to explain what it does. While Objective-C allows for, and even encourages, verbose coding habits, I would rather maintain my old-school approach to comments.

My other comment guidelines work together:

  • Comments should be on their own lines, when possible, so they are easier to spot.
  • Comments should be concise and meaningful.
  • Cryptic comments are worse than uncommented code.

I don't encourage "over-commenting" code. Instead, comment as much as necessary — and no more.

For more thoughts on comments and coding style, Google has published their internal style guide for code. Google encourages programmers to adopt these guidelines:

http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Comments


[possible tags: Objective-c, Cocoa, Apple, programming, computers, comments, writing, notes, planning]

Comments

  1. Here I must humbly disagree. Boilerplate comments tend not to fare well under maintenance. Conside the file header comments:

    * File: main.c

    The file name might change due to refactoring or just choosing a better name. The refactoring tools don't touch comments. You can see the file name in the Xcode UI, or whatever your tool of choice is.

    * Program [or Function, etc]: Hello World C

    A useful chunk of code might end up in other projects with no relation to the original. The name of the project might change too. It's not useful information.

    * Copyright (c) 2013 Tameri Publications.

    These are ok

    * 2013-04-04 Created by CSW
    * 2013-04-10 Expanded printf() examples

    This is what source code control is for. After more than 5-10 revisions this kind of set up gets worthlessly wordy.

    "Created By" is rarely interesting. Often, someone will create a file, then move to another project. Then they keep getting email "hey I found a bug in Borkinator.m!" even though they havent been on the project in years. This information (along with who last touched it) also belongs in source code control.


    * TODO Add other output function examples

    These are ok - but best to put near what needs fixing. I like putting a name on it - with a multi-person project, knowing who put in the todo is good so you can say "ok, you said "add other output function. What functions, exactly". One team I'm on dates them too:
    // (markd/2013-05-16)TODO: add examples of bad pointer dereferencing.
    TODO that's five years old can probably just be removed :-)

    ReplyDelete
  2. The boilerplate is better than no comments -- but they should be replaced with something useful.

    Your comments on code reuse are important, especially when working with teams. You still need to explain a function, when appropriate. Concise comments, when essential. It is hard to know what will or won't seem obvious in a year.

    The "Created by" likely reflects my dealings with compliance issues. We used to keep binders (ugh) of change requests and logs for federal regulators. No code could be changed without a detailed paper trail. Thankfully, we were permitted to move those into comments over time and stop printing the code. It was all very Dilbert in nature, since nobody used the binders.

    It would be interesting to compare code comment styles from an industry and purpose perspective. I remember being told to add comments explaining what the function "VideoPageCopy(apage, mpage)" did. There were more comments than code.

    ReplyDelete
  3. The more I think about this post, the more I realize that it reflects the "ancient times" when I learned to code. There might be two, maybe three source files in a project, an external library (maybe), and that's it. There was no version control, no source code repositories. You coded in one big text file, using something like ISPF on the IBM mainframe, and hoped that the chargeback for compiling time didn't spiral out of budget.

    I remember being asked by my boss about the "charges" for a program. I had been trying to eliminate bugs in a massive programs. Ah, the days of JCL and time shared computing.

    Today, a "simple" program might have hundreds or thousands of small files. A simple exploration of the foundation.h headers is mind-boggling. Few programs are going to be a single source file, maintained by one person.

    When I used to print source code, having the file name repeated, along with any other useful info, saved hours of time. Do people even print their source code? And if you do print it, any good editor will have the ability to include file names, paths, line numbers, and other useful markers.

    Quite simply, I'm an out-dated dinosaur still not familiar with what has happened over the last computing epoch. Code reuse, once something we joked about as a dream, is now the norm. Code is not monolithic, at least not outside textbooks and dated lectures.

    Now I wonder how my commenting strategies might change as I delve into more current programming languages and tools.

    ReplyDelete

Post a Comment

Popular posts from this blog

Learning to Program

Late last night I installed the update to Apple's OS X programming tool suite, Xcode 4. This summer, in my "free" time I intend to work my way through my old copy of Teach Yourself C and the several Objective-C books I own. While I do play with various languages and tools, from AppleScript to PHP, I've never managed to master Objective-C — which is something I want to do. As I've written several times, knowing simple coding techniques is a practical skill and one that helps learn problem solving strategies. Even my use of AppleScript and Visual Basic for Applications (VBA) on a regular basis helps remind me to tackle problems in distinct steps, with clear objectives from step to step. There are many free programming tools that students should be encouraged to try. On OS X, the first two tools I suggest to non-technical students are Automator and AppleScript. These tools allow you to automate tasks on OS X, similar to the batch files of DOS or the macros of Wor

MarsEdit and Blogging

MarsEdit (Photo credit: Wikipedia ) Mailing posts to blogs, a practice I adopted in 2005, allows a blogger like me to store copies of draft posts within email. If Blogger , WordPress, or the blogging platform of the moment crashes or for some other reason eats my posts, at least I have the original drafts of most entries. I find having such a nicely organized archive convenient — much easier than remembering to archive posts from Blogger or WordPress to my computer. With this post, I am testing MarsEdit from Red Sweater Software based on recent reviews, including an overview on 9to5Mac . Composing posts an email offers a fast way to prepare draft blogs, but the email does not always work well if you want to include basic formatting, images, and links to online resources. Submitting to Blogger via Apple Mail often produced complex HTML with unnecessary font and paragraph formatting styles. Problems with rich text led me to convert blog entries to plaintext in Apple Mail