Best practices for naming functions

Question

I would like to know which tenses are most used to name the functions.

For example, there is a more suitable in this hypothetical case?

Calculadora calculadora;
calculadora.soma(3, 4);
calculadora.somar(3, 4);

or

int obtemValor();
int obterValor();

What is the best verbal time to use when naming functions?

Answer 1

TL;DR

This is a topic whose personal opinion influences a lot, but there are some general good practices that can be extracted for nomenclature and standardization of methods.

Standard

Each language suggests or even limits the nomenclature of methods and functions.

Usually when dealing with objects the preference is to use the pattern Camel Case, that is, the initials of the words are capitalized:

comerCoxinha();

When we talk about functions in languages such as Python, PHP or Javascript, it is not uncommon to find the use of underline or underlined:

comer_kibe();

In this aspect, the important thing is to maintain pattern and consistency both in how the words that make up the name are linked as in relation to the verb, language and word order.

Grammar class and tense

Different grammatical classes such as verbs, nouns, prepositions and adjectives can be used to name functions and methods if used within the correct context.

Nouns and Adjectives

Nouns and adjectives are usually used to name variables, classes, and attributes, since these elements usually refer to something or someone.

Example:

class Carro {
}
class CarroColorido extends Carro {
    String cor;
}
carrinhoVermelho = new CarroColorido("vermelho");

Note how CarroColorido and carrinhoVermelho are compositions of noun and adjective that help to understand what these elements refer to.

Verbs

There is no general consensus, but many books and implementations suggest the use of verbs in methods, since they denote stocks of an object.

However, in practice many end up using different tenses. For example, some understand that they should use infinitive tenses. In this case, the correct for the Calculadora would be the method somar.

Others prefer to use the imperative, as ordering the object to do something. In this case, the order for the Calculadora would be some.

When naming the method soma:

• Or you are using the imperative incorrectly, which is not uncommon in Brazil;
• Or are you using the noun to refer to the action of somar, as saying to the object "make the sum".

A lot of confusion arises because methods named in English can have both the connotation of imperative and infinitive. For example, execute() can be understood as much as to execute (perform, in infinitive) how much execute (perform, in the imperative).

Methods getters and setters

Attribute access methods are usually an exception and are named according to their attributes.

Most of the time you’ll find something like setNome(String) and getNome() to change and recover the value of an attribute, respectively nome.

It is also not uncommon to find such methods without prefixes get and set, such as nome() to recover and nome(String) to change. Particularly I prefix this pattern.

Fluent interfaces

Several grammatical classes end up being welcome when we use the standard Fluent Interfaces.

The goal here is to make the code more readable and easy to use and not simply follow a pattern blindly.

An example of a possible database access API:

query = Consulta.select("nome").from("cliente")
            .where(Criterio.maiorOuIgual("credito", 1000))
            .and(Criterio.igual("cidade", "Foz do Iguaçu"));

Although I have mixed languages, nouns, prepositions, the above code can be easily understood. The parts in English are SQL language and the rest can be understood without reference to the documentation.

Putting it all together

As I said, there is no rule, but it is recommended to follow a standard. Even so, there are different patterns for different contexts that, coupled with different techniques, allow a coherent class model.

I believe that the question to be asked of each method created is:

From the point of view of client code (which calls the method), this name makes sense and makes clear the purpose of the method, including its side effects?

Answer 2

Each team has its own standard, there is nothing universal. I studied the subject and concluded that each group of people chooses what they think best, but I found a pattern in better written codes, usually by recognized professionals. Also I found some style guides that indicate certain patterns, some of them that can be considered "official". They varied according to language. So I’ll talk about what I found most common. Your mileage may vary.

Some "little rules"

The most common is to use verbs to designate methods and functions, but there are cases that another form of expression may be useful.

The most commonly used time is the imperative, after all you are ordering an action. Expressions whose main component are verbs are also used. A classic example is the getField() (much used in getters and setters). This is easily seen in English.

When methods have a specific function they can use other tenses or even be omitted giving rise to the noun it will produce. For example:

• in events when it indicates something that is yet to happen it is common to use the infinitive. When the event has already happened it is more common to use the past participle. When the event is occurring the gerund is used.

• if the method or function will return a boolean it is common to have a specific construction indicating a capacity. Ex.: is, can, has, isThere (some prefer to use only the has), allow (which may be the same as can). Or in English é or eh, está or estah (usually followed by a verb in the participle or adjective), pode (usually followed by a verb in the infinitive), tem (probably followed by a noun), existe (followed by a noun), contém. The plural can be used, or another conjugation, e.g..: foiTentado or tentou. Note the use of the 3rd person. In some cases the verb may be omitted, but you should avoid doing this. There are cases where the prefix Try indicates this situation, the name says you should try and inform whether it worked or not, it is a convention. It is written thinking it will be used in a question (a condition/predicate).

• when the method actually returns a property, a feature, an obvious object, in short, when it is obvious that what it is trying to get is simple information, it is possible to use a noun, but you cannot abuse it. We can say that it is a form of abbreviation of what the method actually does. Libraries do this in methods such as IndexOf that deep down you’re saying GetIndexOf, or HashCode, that would be CalculateHashCode, or Size, replacing a property (GetSize), Sin (CalculateSin). Note that there is a difference between a pure property that in general must be a noun or adjective and a method that is replacing a property.

  When a property needs more than trivial processing to obtain the result, it is better to use a method than a property, to make it clear that there is a cost in calling that. Some people think that you should still maintain the verb pattern and put at least one Get at the front. Others think this would cause an unnecessary proliferation of Get or Calculate or other obvious verbs. I have seen some people separate into verbs what changes the object and nouns which produces an independent result, when there is purity. Something to consider when eliminating the obvious prefix verb.

• in fluent interface or places where the use has a specific purpose, the expressions can be used a little differently. It is more important to be fluent in reading, although this most often works much better in English than Portuguese.

Em português parece que há mais confusão. Alguns entender que o get is obter, others think it’s obtenha. I see people mixing English with Portuguese in cases like this, but when one decides to translate everything I see it is very common to use the obter. But if we look strictly for the tongue, this is a mistake. toGet would be obter. If this analysis were not enough, some guides are quite clear in saying that the time to be used is the imperative, then the translation would be obtenha^{See comments below for translation variations}.

So the ideal in these examples would be to call calculadora.some(3, 4); and obtenhaValor();. No one considered will say it’s wrong to use calculadora.soma(3, 4); and obterValor();. Some should even require it to be this way, after all it must be the reason the answer has negative.

The idea is to give the reading fluent: "with the calculator add 3 and 4", or "with the variable name separate by comma" (nome.split(',')) or simply "get the value". Hence some even think that the article should not be omitted to give more fluency. It is rare to see codes that do not omit. I can’t say which one is right, I know which one I’m used to. That’s where pure opinion comes in.

Try reading in the infinitive, it looks like a talking machine. Is that how you prefer it? Have you gotten used to it? Okay, I have nothing against, it’s your taste. Do you want to make a mental translation of what is actually written for what you really think, that is, write in the infinitive but read in the imperative? OK for me too. I do it myself in fast codes where I’m not thinking much about how it will be used.

I see they use the infinitive pattern in Portuguese frequently. I believe it is because they follow the pattern of others without making a question of which is correct.

Within this principle the name should not describe what the function does, it should indicate the command. The name should indicate the behavior and not the implementation. It is subtle and even subjective, but it seems to me that the imperative pulls by the behavior and the infinitive pulls by the implementation.

A common error is trying to use a method to change a property. Then the name will already be wrong. It is better to name an action that happens to change a property. Nomenclature is another and it becomes clearer what the behavior is. Eventually having the property changed can even be considered an abstraction leak.

Completion

But what happens if you don’t follow this pattern? Nothing! It’s still understandable. Ideally, always be consistent. The most important thing is the name define the goal well, what it is telling you to do. The problem gets bigger when name indicates one thing and does another. Remembering that pro compiler obviously doesn’t make the slightest difference.

I’m not here trying to change the way people do. If someone has done it one way her whole life she won’t want to change because she read what I wrote here, even though she realizes it makes sense.

Maintain consistency. The important thing is to know what you’re doing. Always! And more importantly, rules were made to be broken when necessary.

The question focuses on functions. For variables, classes and other forms, the pattern should be different, including about the Casing, I have a answer that talks about this in C#, it would make no sense to repeat here.

The subject yields and it fits more specific questions. In fact I agree with the closing of the question because it is broad, not based on opinions.

Just to quote some references I found quickly, beyond the question linked above where I quote the source of the general recommendations I posted:

• Document published at the Universities of Wisconsin/Berkeley and Microsoft Research.
• Book about C#.
• The same for C++.
• Another book about C++.
• Book about Microsoft NAV - web.
• Forum of D.
• LLVM style guide.
• Delphi Guide.
• A style guide for Java.
• Another style guide for Java.
• Article on the use of Javabeans.
• Lua Sockets.
• CQRS style guide.
• Question on the Programmers.
• Tag in the OS. And in the Programmers.
• GUJ - It sucks, but the more articulate show that the path is the imperative :D
• Article about the naturalness of language.

Many books and articles do not speak clearly about using the imperative, but all examples are like this. The book Clean Code is one of the classics to learn about it. Although I don’t agree with everything in it. Another is the Code Complete.

Answer 3

Between the two forms you quoted, I prefer that the verb is in the infinitive, how to get() and add().

Try to name your variables in the same language as the programming language, in this case in English.

Each language has a standard and its best practices. Python, for example, has a PEP 8, a style guide for the developer community. Java should have its, C++ too and so on.

Besides, everything can vary according to the project you are working on. If people are using a specific pattern, the ideal would be to continue the way it was started in order to maintain a pattern.

The link to the slides is also a hint How to name things: the biggest problem of programming.

Answer 4

I always use the name summarizing with the minimum of words what the function will do, example:

class Calculadora {
    public static int somar(int a, int b) {
         return a + b;
    }
}

Java has a different language design than . NET Framework, its functions and classes often use lowercase and uppercase letters to "improve code vision".

somarNumeros java special

SomarNumeros special. NET Framework

somar_numeros I don’t know what it is, but in my opinion it’s the worst way to name something.

Names in Portuguese?

In my opinion, I prefer to use even English for any language I will use, it is much more beautiful to use English to name a function than Portuguese.

int obterValor(); 
int getValue();   //Tudo em inglês, melhor ainda

Defining function names or types depends on the writer of the code, it is not good to mix English with Portuguese in your code, can cause a confusion at the time of understand the code. You should name the method with what it will do, a function with what it will do and what it will return, example:

int getAlunoFromIndex(int i, string[] alunos) {
     return alunos[i];
}

And not like this:

int ObterAlunoPeloIndice(int i, string[] alunos) {}

Always you will perform a function ~~ future

You will get a value ~~ future

That function will use this method here ~~ future

Anyway, this question depends a lot on who will write the code. I recommend using the function name on future of the indicative, and also adapt to the syntax of the language. If there are languages that use all the methods IN UPPER CASE, would you like to see one method in upper case and another in lower case in your code? I was gonna give a stump, is not?

private int OBTER_VALOR = 0;
private int getIdade = 15;
private int ObterPropriedade = "Foo Bar";

Causes a mess, so you choose the way you’re going to use your code.