Short function names for often used function or general concept

Question

I am a bit in a dilemma: Let's suppose I have a very general function and a specialization of it for convenience reasons. Let's also assume that the specialized function is used 90 per cent of the time, hence being "the common case".

Should I use a shorter function name for the general case (e.g. do) and a longer one for the special (do_something_special) or the other way around (e.g. do_something_general and do)? When applying Larry Wall's words (make simple things easy and hard ones possible), I'd use a shorter form for the more often used case.

EDIT: Just to make this a bit more clear: in this example, do is just a placeholder for a short, descriptive name. Of course it could be longer, e.g. run_task or process_file. What I want to know is, if I have a function called run_task_in_specific_way that is used most of time should actually be called run_task (although being more specific) or the general abstraction.

EDIT 2: To clarify once more: The functions I am talking about are neither providing more than one functionality nor should they be replaced by a class-based design. The reason is: they are abstract in the same sense as qsort, e.g. taking callable from users to fulfill a specific action. Wrapping them into some auxiliary class does not make much sense.

Answer 1

Use a name that accurately describes what the function is achieving. If its doing something "special", put "special" in the name. Don't worry about how long the name is (within reason). Over the next few decades, readers deciphering cryptic functions names will take a lot longer working out what they mean than typing the name a few times.

In the above example, I would use "do_general" and "do_special"..... "do" gives no clue that there is an alternate.

Answer 2

Don't you use classes? Or is it a global function? In general you could use short ones like:

<?PHP
class Text {
  public function show() {
  }
  public function hide() {
  }
  public function delete() {
  }
}
class Image {
  public function show() {
  }
  public function delete() {
  }
}

//Implementation, even if we mix them up it stays quite clear and readable:
$firstText=new Text();
$firstText->show();
$imageOfMyFriend=new Image();
$firstText->delete();
$imageOfMyFriend->show();
?>

The class instance name will define what we are talking about. This could also be done with more utility classes which you call static:

<?PHP
  class File {
    public static function read($path) {
    }
    public static function readStream($path) {
    }
  }


  //implementation
  echo File::read('/home/myfile');
  echo File::readStream('/pathToMyStream');
?>

All very simple names but still seems to work for me.

When you have exceptions you can define them in multiple ways. If you really need a seperate public method you can always derive the alternatives (As you see in File::readStream). That is also clear.

Generally I would reduce the public outputs, so make the read function detect whether we are handling a stream for example. It's the same idea, read, so it's the same thing you try to achieve. That makes it possible to switch implementations later on.

Answer 3

Let's take a look at Java's String class.

It has a method length(), which returns the length of a String. Often you need to check if a String is empty (e.g. to check if the user has entered a username in a web form). So you do:

if(username.length() == 0) {
    // Stupid users!
}

For convenience, String has the method isEmpty() since Java 1.6. Now, you need only to do:

if(username.isEmpty()) {
    // Do stuff
}

However, the documentation clearly states what isEmtpy() does:

Returns true if, and only if, length() is 0.

There is nothing wrong with it:

• Keep the general function (obviously)
• Give the specialized function a meaningful name. specialLength() would not give any hint what it does.
• In your documentation, make it clear that your specialized function is only a "shortcut" for an existing function, and describe it.

Answer 4

Based on my experience, I'd go for the middle way. It's better to have the shortest expression instead of having a short code or a sentence as a name. Generally I think you should not sacrifice being expressive for being brief when it comes to naming.

That was my two cents!

P.S. Based on what you just said to mattnz, I suggest to develop a template for naming and name everything following its guideline, no matter short or a bit longer.

Answer 5

I personally never did like "do" very much in code. It isn't very descriptive other than implying that something needs to be executed, but unless it is a getter or setter, it is already implied that you're executing something.

When I want to write code pertaining to a general controller-like method, I tend to call it "execute". How my controller behaves is determined by a configuration set prior to calling execute. If there is a radically different way of working which is a particular case, I'll rename execute into executeDefault and then I'll create a execute. In order to keep it short, I'll simply create a method "execute" at that point which calls executeDefault. In this way, I have the best of both worlds: short name and understandable code.

If I end up having many such execution cases, then I consider restructuring it using the Abstract Factory pattern which provides me controller classes with "execute" method.

Hope that helps.