CODEWITHSUNDEEP
coding-stylecomments
Sebastian Hoffmann
Sebastian Hoffmann

Reputation: 11502

Comment style: Imperative or third person

I have a question relating programming and english language both: Whether to use third person or imperative when commenting single lines of code. Assume following line of code in a imperative language which should be commented:

object.doSomething();

My approach to comment this line would be to put the comment behind it using third person like this would be a ordinary english sentence containing the line as subject:

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

But since we are in a imperative language and thus actually "commanding" the computer, one could even think of putting the comment before the code and using imperative:

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

This is even useful when one need to comment multiple lines related to each other.

I personally prefer the first style but i often feel unsure about what style to use. It would be great if some could write their personal experience down here.

Upvotes: 45

Views: 14490

Answers (6)

iki
iki

Reputation: 121

Conventional commits use imperative present tense

What writing form should I use?

We recommend writing a commit description and body using the imperative present tense writing form.

There are a significant number of examples of this writing form for commits 1 2 3 4 5

Similarly to Python using imperative mood in docstring in answer above

Upvotes: 0

Maciej Kravchyk
Maciej Kravchyk

Reputation: 16727

I think the most common pattern I have seen is to use third person when describing classes, methods and functions definitions, and imperative mood when commenting pieces of code, function calls etc.

So when you have a comment on top of a function definition, you are describing what the function does. So you use "Creates foo" rather than "Create foo"

// Creates a Foo object
function create_foo() {
// ...
}

Then if you need to describe a function call, use imperative mood.

// Create a Foo object
create_foo();

Upvotes: 7

Vicne
Vicne

Reputation: 423

Google has clear directives making a distinction between documentation targeted at implementers of an interface (explain what to do, imperative style) and documentation targeted at users of a library (explain what it does, third person style), which is your case.

Admittedly this distinction makes little sense for line-level comments, which always explain what the code does.

In other words, it's 3rd person for me.

https://developers.google.com/style/reference-verbs

Upvotes: 9

wstomv
wstomv

Reputation: 891

For Python, PEP-257 states about docstrings (emphasis added):

The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

And PEP257: Good Python docstring by example is even more explicit (emphasis added):

Note that all docstrings begin with a one-line summary. The summary is written in the imperative mood ("do", "use", "find", "return", "render", etc) and ends with a period.

Upvotes: 29

Robin Nabel
Robin Nabel

Reputation: 2310

Oracle's official style guide states:

Use 3rd person (descriptive) not 2nd person (prescriptive). The description is in 3rd person declarative rather than 2nd person imperative.

Gets the label. (preferred)

Get the label. (avoid)

Oracle's style guide can be found here.

Upvotes: 40

Darren Burgess
Darren Burgess

Reputation: 4332

The first approach is definitely the more appropriate method of commenting, as it will be people reading your comments it is important that they are as easy to read as is possible. //Do somethingsounds like you are talking to the computer as opposed to explaining what the code does.

Upvotes: 8

Related Questions