"I", "We", or Neither in code documentation

Question

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type:

The reason we are doing this is...

The reason I use "we" instead of "I" is because I do a lot of academic writing where "we" is often preferred.

So here's the question. Is there a good reason to prefer one over the other in documenting code:

1. Use "We": The reason we are doing this is...
2. Use "I": The reason I am doing this is...
3. Use my name: The reason [my name] did this is...
4. Passive voice: The reason this was done is...
5. Neither: Do this because...

I choose #1 because I'm used to writing that way, but documentation is not for the writer, it's for the reader, so I'm wondering if adding the developer name is helpful or if that just adds yet another thing that needs to be changed when maintaining the code.

Answer 1

I'd go with:

#6. Declarative: ...

Rather than say "The reason this was done is because each Foo must have a Bar", just say "Each Foo must have a Bar". Make the comment into an active statement of the reason, rather than a passive one. It's generally a better writing style overall, better fits the nature of code (which does something), and the the reason this was done phrase adds no information whatsoever. It also avoids exactly the problem you're encountering.

Answer 2

I prefer neither, and actually would leave off that introductory phrase altogether and just get to the point. I also try to avoid just saying "this" because it leaves no way to tell if the comment is in sync with the code. In other words, instead of:

// The reason this was done is to prevent null pointer exceptions later on.

I would say:

// Frobnicate the widget first so foo can never be null.

The fact you're adding a comment at all implies you are stating a reason, so you don't need to redundantly tell people you're explaining the reason. Just make the reason as specific as possible, so they know as clearly as possible how to maintain that code later on.

Answer 3

In C# (and in most documentation tools in other languages) there is a difference between documentation and in-line commentary. My personal opinion is that you should always use formal, declarative-style comments as Bobson and others suggest in the documentation of a class or member, but within the code, there's nothing wrong with being less formal. In fact, sometimes an informal comment is more effective at explaining why something is being don than a full exposition in formal English.

Here's a sample which I think illustrates the point.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

Answer 4

Another idea to consider would be a well crafted unit test that demonstrates why the code works the way it does in place of writing a descriptive comment. This has a couple benefits over writing comments:

1. Comments do not always change when the code is changed which can lead to confusion later on.

2. Units tests give the maintainer a easy way to play with the code. Learning a new codebase can be a lot easier if you have individual units that you can break to observe what changes.

Even though this avenue requires more work up front, unit testing can be an excellent form of documentation.

Answer 5

Good comments are hard to write, and even the best comments are often hard to read and comprehend. If your comment is concise enough for me to absorb and precise enough to convey what I need to know about the code, it doesn't make me any difference what pronouns you use.

I would hate to discourage somebody from commenting their code because they're concerned about the case, tense, and person of their pronouns.

Answer 6

The reason I use "we" instead of "I" is because I do a lot of academic writing where "we" is often preferred.

It is a bad style, even for academic papers, unless you are trying to hide who actually decided that exact point.

As for your specific question : I wouldn't leave such comment, unless it starts with :

// TODO: clean this up, ...

or unless it explains something very important, that might not be so clear from the code. In that case, make the comment as brief as possible.