Grammar style for code comments

There are several commenting styles in use.

Some programmers use a terse style like:

// Get value

Others write sentences in plain English language, like:

// This should get the current measured value.

When using natural language, some programmers use imperative form, like:

// Get the value.

while others use the indicative form, like:

// It gets the value.

sometimes shortened as:

// Gets the value.

Of course, it is better to use a uniform style; and if several programmers access the same code, a rule should be written be guide programmers to get such uniform style.

I propose (and, when possible, use) the following rule:

Inside the body of a function, always use the imperative form; outside use the indicative form.

The rationale is the following.

The body of a function is the implementation of the algorithm, and therefore it is procedure in nature, or, as it is said often, “imperative”. It is imperative as the statements are meant as orders that the programmer send to the computer. Of course, here I am talking only of imperative languages.

Comments inside function bodies are a usually pseudo-code, i.e. higher-level code that is typically written before the code itself as a specification, and then the comment is implemented by writing real code. If the code is quite self-explanatory, there is no need of comments. Comments are explanations for somewhat cumbersome implementations. These comments are a kind of natural language imperative programming, and therefore they should use the imperative form.

For example, here is a good comment:

// Check input until you reach end-of-file.
while ((ch = getchar() != EOF) ;

and here is a bad comment for the same code:

// It checks input until end-of-file is encountered.

The comments written just before function bodies are meant to explain the purpose of the function, not the implementation. They said what the function does, not how.

They are more a kind of declarative specification than a kind of imperative programming, even if the function is quite imperative and the function name is an imperative verb. These comments are not natural language imperative programming, they are natural language specification. Therefore an indicative verb is more appropriate.

Here is a good example of comment;

/// It returns the square root of "x", if "x" is non-negative.
/// Undefined otherwise.
double sqrt(double x);
Advertisements

About Carlo Milanesi

I am a software developer in Italy. I have develop financial, engineering and commercial software using many programming languages, mainly C, C++, Visual Basic, Java, and C#. Now I am interested in Rust and TypeScript.
This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s