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

Comic Sans Is (Generally) Lousy: Letters and Reading Challenges

Specimen of the typeface Comic Sans. (Photo credit: Wikipedia) Personally, I support everyone being able to type and read in whatever typefaces individuals prefer. If you like Comic Sans, then change the font while you type or read online content. If you like Helvetica, use that.

The digital world is not print. You can change typefaces. You can change their sizes. You can change colors. There is no reason to argue over what you use to type or to read as long as I can use typefaces that I like.

Now, as a design researcher? I'll tell you that type matters a lot to both the biological act of reading and the psychological act of constructing meaning. Statistically, there are "better" and "worse" type for conveying messages. There are also typefaces that are more legible and more readable. Sometimes, legibility does not help readability, either, as a type with overly distinct letters (legibility) can hinder word shapes and decoding (readability).

One of the co…

Let’s Make a Movie: Digital Filmmaking on a Budget

Film camera collection. (Photo credit: Wikipedia) Visalia Direct: Virtual Valley
June 5, 2015 Deadline
July 2015 Issue

Every weekend a small group of filmmakers I know make at least one three-minute movie and share the short film on their YouTube channel, 3X7 Films.

Inspired by the 48-Hour Film Project (48hourfilm.com), my colleagues started to joke about entering a 48-hour contest each month. Someone suggested that it might be possible to make a three-minute movie every week. Soon, 3X7 Films was launched as a Facebook group and members started to assemble teams to make movies.

The 48-Hour Film Project, also known as 48HFP, launched in 2001 by Mark Ruppert. He convinced some colleagues in Washington, D.C., that they could make a movie in 48 hours. The idea became a friendly competition. Fifteen years later, 48HFP is an international phenomenon, with competitions in cities around the world. Regional winners compete in national and international festivals.

On a Friday night, teams gathe…

Edutainment: Move Beyond Entertaining, to Learning

A drawing made in Tux Paint using various brushes and the Paint tool. (Photo credit: Wikipedia) Visalia Direct: Virtual Valley
November 2, 2015 Deadline
December 2015 Issue

Randomly clicking on letters, the young boy I was watching play an educational game “won” each level. He paid no attention to the letters themselves. His focus was on the dancing aliens at the end of each alphabet invasion.

Situations like this occur in classrooms and homes every day. Technology appeals to parents, politicians and some educators as a path towards more effective teaching. We often bring technology into our schools and homes, imagining the latest gadgets and software will magically transfer skills and information to our children.

This school year, I left teaching business communications to return to my doctoral specialty in education, technology and language development. As a board member of an autism-related charity, I speak to groups on how technology both helps and hinders special education. Busin…