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.

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.

share|improve this question
1  
possible duplicate of Why are cryptic short identifiers still so common in low-level programming? - this terrific answer covers all bases with Zipf's Law –  gnat Oct 2 '13 at 7:43
    
Could you please be some more specific what your function is about? It is described very abstract here. Does process_file do everything with files, like create, read, update, delete, move, copy etc.? It seems to me that your function does more than one thing, which is bad for your program's design (and lead to problems like this). I think your root issue is a different one. –  Uooo Oct 2 '13 at 10:30
    
The functions are abstract. In my particular case they are skeletons which are outlining some algorithm but calling into whatever the user provides for specific details. I'll update the question. –  matthias Oct 2 '13 at 10:34
    
@matthias What language are you using? Some languages have the ability to use or fake named and/or optional arguments, which would make for a far more elegant solution that choosing different names. –  amon Oct 2 '13 at 11:10
    
I am currently facing this in Python. But, the problem itself is not very specific to any kind of language IMHO. –  matthias Oct 2 '13 at 11:54

5 Answers 5

up vote 0 down vote accepted

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.
share|improve this answer
    
Ok, that is clear advise. I'll accept that for now, thanks ;-) –  matthias Oct 2 '13 at 15:19

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.

share|improve this answer
3  
The example is a bit misleading. You can assume that do does sufficiently describe the functionality. So, for example the argument to do could be task. –  matthias Oct 2 '13 at 7:05

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
    
Sorry, my do was a bit misleading. I tried to clarify it in an edit to the question. –  matthias Oct 2 '13 at 9:29

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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