Should actions / methods be conjugated in comments?

Question

For example, which of the following is correct ?

// Return hello
      -- or --
// Returns hello

function greeting()
{
  return "Hello";
}

I personally never conjugate them but I am wondering how right or wrong this does sounds to a native english speaker. I have been unable to find a real recommendation about it.

Another example:

// Find the first entry (implicit "to find the first entry")
      -- or --
// Finds the first entry (implicit "this finds the first entry")

function findFirst(array)
{
  return array[0];
}

Answer 1

If you have some doubts about naming and documenting, check out how top developers do it. You can find good examples in official documentation for different tools, libraries, frameworks, languages etc.

For example,

• MSDN Stack<T> documentation
• PHP.net mysqli::ping documentation

Description of the methods contains conjugated forms such as "Specifies", "Returns", "Removes" or "Determines", while comments within methods use imperative forms - "check connection", "check if server is alive", "close connection", "Create a copy of the stack".

So, I'd write your code like this:

// Returns hello
function greeting()
{
  return "Hello";
}

// Starts foo-ing
function foo()
{
   // Show greeting message
   greeting();
}

Upd: And this makes sense, because comments before functions and methods tell us what the functions do:

• Foo() returns the state
• Bar() checks the value

while comments in functions show us the steps of the algorithm:

• Get the state
• Check the value
• Initiate the module

Answer 2

Conjugation being very rudimentary in English, I would say it doesn't make much of a difference. It might as well be the imperative, particularly if the method is a command in the context of command-query separation. Personally, that is how I read it, because in Slovak, my native language, buttons are commonly labeled with the imperative (which is morphologically clearly distinct from the infinitive in that language).

// Find the first entry (implicit "onward, contraption, find me the first entry!")

function findFirst(array)
{
   return array[0];
}

However, if the method name is well chosen, you don't need to rephrase it as a sentence. Instead you document side effects, usage and what not, in which case the imperative is inadequate and one would use the 3rd person indicative. People will of course have dozens of different opinions of this and some will start religious wars over it. Ideally you can let someone else review the code and if they understand what a method does based on its name + documentation, then you have done it right, otherwise not. Further distinctions border on bikeshedding.

Just an example of a method not quite well named:

function greeting()
{
   return "Hello";
}

The name in itself leaves multiple options open. Does this actually perform the greeting? Or does it give me a value suitable to greet others?

If performed the greeting itself, then I would call it greet (or performGreeting if no suitable verb is available or the verb is ambiguous) and otherwise makeGreeting (or produceGreeting or provideGreeting or somesuch).

Answer 3

Unfortunately, there is no real rule that states what you are asking about.

Personally, my comments behaviors depend on the programming language I am coding with. As I develop for example in Python, I can show that your first option (return) is rather favored in this programming language: If you check PEP 0008 and read the whole comments paragraphs, you will see we rather use your first option:

x = x + 1 # Increment

x = x + 1 # Compensate for border

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first. """

Answer 4

I'd do neither. The type of comments you are describing are simply there to describe what badly named methods are doing. They are noise.

Instead of calling a method findFirst and then having a comment that described what findFirst means, call the method findFirstEntry and remove the comment.

The purpose of well written code is to tell other developers (and the compiler) what that code does. If additional explanations of why it does it a certain way, or how a necessarily complicated piece of code works, then add clearly written comments. If the code is clear, don't clutter it with pointless comments that just repeat the code.