current community

your communities

more stack exchange communities

Stack Exchange
tour help
Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
up vote 2 down vote favorite

I often have naming problems when I write classes and functions. Generally speaking, I try to follow the following set of rules if I have to deal with a function whose name is a verb:

  • If the function alters the parameters, use an infinitive.
  • Otherwise, use a present participle.
  • If the function is a boolean, use is, has or can before the infinitive.

I thought that this rule made sense, but looking at standard libraries of several programming languages, I feel rather alone. For example:

  • Python's string methods do not alter the strings but are name with infinitive verbs (e.g. capitalize, split, strip...).
  • D's std.functional functions return new functions but are named with infinitive verbs too (e.g. memoize, curry...).

While it would have made sense to me to use strip (had Python strings been mutable) to alter a string and stripped to get the a new string (similar to the one passed but stripped from its leading and ending spaces), it seems that such a convention is almost never used (however, Python also provides the built-in functions reversed and sorted which do use past participle to tell that they respectively return a reversed or sorted collection without modifying the one passed to them). Are there contraindications concerning the use of past participle for the names non-altering functions and methods?

EDIT: I fail to see what is unclear, so I'll sum up the question in a few words:

Is it bad pratice to use past participle instead of imperative or infinitive verbs to name functions that take a single parameter, do not alter it, but return an altered copy of the said parameter?

share|improve this question

closed as unclear what you're asking by Robert Harvey, gnat, GlenH7, World Engineer♦ Mar 21 at 13:43

Please clarify your specific problem or add additional details to highlight exactly what you need. As it's currently written, it’s hard to tell exactly what you're asking. See the How to Ask page for help clarifying this question.If this question can be reworded to fit the rules in the help center, please edit the question.
    
Is there a difference between the imperative form of a verb and the infinitive? I looked up and saw they are different verb modes, but it looks like there's overlap. –  Rob Y Mar 20 at 23:15
    
In French, there is. The imperative is when you order "do that", and the infinitive is a neutral form, generally the one preceded by "to", you say that you have a function "to do that". You can find the difference between the moods in this article. –  Morwenn Mar 20 at 23:20
    
I think French is (as usual) less muddled on the issue than English. Would you name a verb ob.inverser(a) or ob.inversez(a). Maybe the French practice is to use the infinitive to avoid the formal/personal distinction (?) –  Rob Y Mar 20 at 23:31
    
@RobY I would use ob.inverser(); imperative would be awkward. But ob.inversé() would make sense though. –  Morwenn Mar 20 at 23:32
    
@RobY Or I would use obj.inverse(), the noun form, which would also be valid in such a case. –  Morwenn Mar 20 at 23:35

3 Answers 3

up vote 1 down vote

I've done software development professionally in many different languages: C, C++, Java, Perl, C#, C++/CLI, Python and Objective-C. The more I use Objective-C, the more I like the clarity of its names.

Non-altering methods are nouns named after the return type.

-stringByTrimmingWhitespaceCharacters and -capitalizedString are both descriptive and are distinct from methods which modify an object. In this case, if the methods modified a string, they would be named -trimWhitespaceCharacters and -capitalize.

otherString = [[string stringByTrimmingWhitespaceCharacters] capitalizedString];

Or in Java style:

otherString = string.stringByTrimmingWhitespaceCharacters().capitalizedString()

At first glance it seems wordy, but it grows on you (at least it did with me).

I now use the Apple Naming Methods guidelines for the programming I do.

share|improve this answer
up vote 1 down vote

It's a little blurry about what the direct object is supposed to be. By default, with no parameters, since "self" is an implicit first parameter, you'd expect the direct object of tenderize to be self.

void MyObject.tenderize()

myObject.tenderize()

If you pass a parameter, it's reasonable to expect that parameter to be the direct object:

void MyObject.tenderize(MyStuff stuff)

myObject.tenderize(stuff)

But if you're following and immutable paradigm, as with strings or functions, it's reasonable to expect that the direct object is the return value rather than the (immutable) input:

String MyObject.tenderize(String string)

string = myObject.tenderize("foo")

Function MyObject.immortalize(Function original)

function = myObject.immortalize(someFunc)

"foo" is immutable (obviously), so it makes sense to go to town on the return value rather than the de-referenced input.

...

For mutable parameters, the convention is that if the function has a return type, then leave the parameter alone:

MyObject MyObject.tenderize(MyObject)

changed = myObject.tenderize(original)

That is, the preference is to make the return value the direct object of the verb. Even in the mutable world, there's a reluctance to change the state of something passed in to a method.

...

In imperative coding, it makes sense to name methods after verbs, and to use the imperative sense of the verb. IMHO it sounds more natural to make use a more imperative form.

...

Ah, OK. Here's what I was tripping over:

http://www.vocabulix.com/grammar/imperative-sentence-english.shtml

It is very easy to form the imperative sentence: Simply take the verbs' infinitive form (without the "to" infinitive indicator).

So in the horrible mess that is English, the infinitive and imperative are very closely related. I think the intent in English is to use the imperative for functions or methods. (In keeping with the American sterotype of being pushy and impatient.)

...Unless you're applying math functions, in which case the name is a noun (!), in sense is "of", as in "square root of", "cosine of", "log of" etc.

The upshot is, some day the English-speaking people of the world will have to apologize to everyone.

share|improve this answer
    
In other words, the infinitive form of the verb is always used? –  Robert Harvey Mar 20 at 22:23
    
I guess I'm trying to rationalize the infinitive in the case of immutable parameters. –  Rob Y Mar 20 at 22:26
1  
It's always the infinitive. I've never seen a participle form, except maybe for the is and has forms, although that would start to sound very LOLCATS. –  Robert Harvey Mar 20 at 22:31
    
I can understand the rationale for immutable objects, but it often bogged me for mutable ones. Sometimes, it is not intuitive whether the mutable object will be modified or not. –  Morwenn Mar 20 at 23:00
1  
FYI, just thinking broadly, if the return type is void, then it just makes sense to modify the parameter. But if there is a return type and a parameter, the convention (stress convention) is to leave the parameter alone. Ultimately, though, if you are consistent with your usage in your code, then people will figure it out. As a famous Frenchman said: "You are free -- choose!" –  Rob Y Mar 20 at 23:57
up vote 0 down vote

I suspect the major problem is readability, and that your idea doesn't flow as well for objects.

foo = capitalised(stripped(bar))

Seems perfectly reasonable English. But when you use objects, especially fluent ones, it starts to get less fluent:

foo = bar.stripped().capitalised()

Perhaps to Germans the fluent version would read better (but I don't read German, I just recall they often order the noun differently).

Also, so some people the extra letter or two on every name would be a disadvantage. Anyone who shaves a few letters out of "strlen" and "strcpy" is likely candidate:

strcpy(foo, stripped(bar), strlen(bar));

I mean, in that call alone we saved SEVEN letters by making the function names hard to read. By that measure, your functions should be "strp" and "caps". And this hasn't gone away, we have the C++ "std" library (not a collection of sexually transmitted diseases) and even Python has "bin" and "chr".

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.