Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
I think it's down to personal preference. I don't see any reason why one would be more clear than the other in general. –  ConditionRacer Mar 15 '13 at 18:51
6  
How about #5: "When in the course of human events..." ;) –  waxwing Mar 15 '13 at 19:36
8  
"Four score and seven seconds ago our forefathers did learn that the foo must be barred least our forces be overcome with NULL" –  Philip Mar 15 '13 at 20:37
    
Strongly related on English.SE: Why do programmers always use 'we' when really they mean 'me' or 'you'? (Which was, unfortunately, closed) –  Izkata Mar 16 '13 at 0:15
2  
Why don't say This code was written like this because...? (Passive voice) –  Alvin Wong Mar 16 '13 at 6:35

6 Answers 6

up vote 75 down vote accepted

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.

share|improve this answer
    
would you mind elaborating a bit on why would you do that? Without an explanation, this answer looks more like a bare opinion, somewhat conflicting with back it up guidelines: '...Opinion isn’t all bad, so long as it’s backed up with something other than “because I’m an expert”, or “because I said so”, or “just because”. Use your specific experiences to back up your opinions, as above, or point to some research you’ve done on the web or elsewhere that provides evidence to support your claims...' –  gnat Mar 15 '13 at 18:54
15  
@gnat "The reason this was done" doesn't add anything to the explanation. Comments should contain just enough text to get the point across and no more. Leave off the niceties, preambles, and other filler text. –  David Harkness Mar 15 '13 at 18:55
    
@gnat - I actually had just finished adding more when I saw your comment. –  Bobson Mar 15 '13 at 18:57
1  
I think my example was too simplistic, because indeed "the reason this was done" doesn't add anything. But there are cases when a tricky situation requires some explanation, and in that case, I find it more natural to use "we" or "I", just as I used "I" several times in this comment. But I think your answer is clear in spirit: "declarative" suggests: use the least amount of words that get the point across clearly. –  Lex Mar 15 '13 at 23:36
7  
I read // as because in most cases. –  Ilmo Euro Mar 20 '13 at 8:49

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.

share|improve this answer

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);
    ...
}
share|improve this answer
4  
Side note: SanitizeData should return a SafeComplexObject. ;) –  Jon Purdy Mar 16 '13 at 5:37

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.

share|improve this answer

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.

share|improve this answer
    
Let me clarify: for comments that will become part of formal documentation, a more formal tone is appropriate, and "I" and "we" are best avoided. What I had in mind with this answer was the occasional explanatory comment, for example when you've done something that will look wrong to the next guy. In those cases, where only people who work in the same code base will ever see it, I say do whatever will convey your meaning most clearly, even it it's I wrote the code this way because... or what we really need here is.... In those cases, a clear comment is more important than a strict style. –  John M Gant Mar 15 '13 at 20:55

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.