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