Comment style: imperative or third person

Question

I have a question related to programming and the English language: how to use a third party, and imperative when commenting on individual lines of code. Suppose the following line of code in an imperative language is to be commented on:

object.doSomething(); 

My approach to comment on this line would be to post a comment behind it using a third person like this would be a normal English sentence containing the line as a subject:

 object.doSomething(); // does (referencing to the line of code) some action 

But since we are in an imperative language and thus actually “command” on the computer, you might even think about putting a comment in front of the code and use the imperative:

 //Do some action: object.doSomething(); 

This is even useful when you need to comment on a few lines related to each other.

I personally prefer the first style, but often feel insecure about which style to use. It would be great if someone could write their personal experience here.

Answer 1

The first approach is certainly a more appropriate commenting method, as the people reading your comments are very important that they are as easy to read as possible. //Do something sounds like you're talking to a computer, not explaining what the code is doing.

Answer 2

The official Oracle style guide states:

Use a third person (descriptive) rather than a second person (prescriptive). The description is written on the 3rd person, not on the 2nd person.

Gets the label. (Preferably)

Get a shortcut. (To be avoided)

The Oracle style guide can be found here .