1

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)?

Improve this question
4
  • Are you adding comments to the code (which will be read only by programmers) or writing formal documentation which will have a more general readership?
    – Andrew Leach ♦
    Jul 30, 2013 at 10:27
  • 2
    Option no. 1 does not work. You cannot use ‘it’ in this manner, though you could use ‘this’. As you say, though, it gets repeated and is not ideal. 3 works, but only in the plural. 2 can work, but sounds somewhat odd (the implied subject is the bit of code being commented). 4 and 5 are the most commonly used, and the ones that sound most natural. Both the infinitive and the gerund have the same meaning of a generic description in this particular context.
    – Janus Bahs Jacquet
    Jul 30, 2013 at 10:31
  • To: Andrew Leach. I've edited it. It will be only read by programmers
    – Fran Arjona
    Jul 30, 2013 at 11:25
  • I prefer writing documentation in the second person imperative form. "Remove the files."
    – oosterwal
    Jul 30, 2013 at 23:38

1 Answer 1

Reset to default
4

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.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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