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]