Learn English – Should I write documentation on first person plural or on third person singular

programmingthird-personwriting-style

I'm a Spanish computer programmer and I usually write code and documentation in my native language, but lately I'm trying to migrate them to English. The point is this kind of writing is quite formal (maybe scientific) and oriented third person to read it (and understand it).

I don't know what should be the best point of view when I comment the code. I have doubts especially between first person plural, third person singular and if I can skip the subject in these or another cases.

In practice, I'm trying to describe a piece of code that do something (it will be only read by programmers). These are the options (if you think another better I'd appreciate it):

  • 1 . // It removes the files => This sounds good to me, but I'm repeating "It" constantly
  • 2 . // Removes the files => Sometimes used by another people, is this correct? (skip the subject)
  • 3 . // I/We remove the files => I think this is quite objective (but very common in Spanish, sometimes without the subject)
  • 4 . // Remove the files => Widely used by English, but I'm not sure if this is grammatically correct (because it's referring to the code (third person singular)). If this is fine, it's supposed to be a second person singular (because of the lack of -s)? An special rule? Maybe an imperative? In that case it would be too much direct and we're explaining the code, not you
  • 5 . // Removing the files => I think this is wrong. In fact I'm going to do it, but I'm not doing it now

So, what's the best way to write documentation in an appropriate style (formal and objective)?

Best Answer

The next person to look at the code will be so grateful that you wrote accurate comments that he/she will not care a bit about small grammar issues. Don't let this sort of thing slow you down at all.

In my own code, I use type 2 (present tense) for declarations and other things that are always true, independent of execution. For example, consider a subroutine that computes the arc tangent.

// Computes the arc tangent of y/x double atan(x,y);

In the middle of running code, I use the imperative. For example,

// Reject 0/0

// Handle x==0 specially

// Compute sign of result

// Map everything into first quadrant

Hope that helps.

Related Topic