The Virtues of Long Names

Wednesday, May 18, 2005

What's right with the parameter names in the following method:

private string ReadTextFile(string sFullyQualifiedLocalFilePath,
                            bool fThrowOnIOError){
    // ...
}

I'm not talking about Hungarian notation. What I want to discuss rather, is the conventional wisdom that "in a short method, local names should also be short".

Here's why I think that rule is misguided: The shorter your functions are, the more functions will you need to look at when debugging the project. And then, it's much better if names are consistent, if like things have like names, and distinctions show up in the names. What's the point of having a variable "file" that refers to a URL, a simple file name, a relative path, an absolute path, a FileInfo object, a FileInputStream, a TextWriter, a boolean flags meaning "save to file, not to the database", all depending which routine you're working on? What's good about a parameter "d" that stands for distance, some double, a DataSet, or who-knows-what else, depending on who wrote the code?

Names have a way of sticking; that's why we use them in the first place. It is not about naming conventions at all to say that names have to make sense. They have to make sense, so we can take advantage of the associative powers of our brains. Constant redefinition - which is what you get if you think that uniqueness of names within a block is good enough - contradicts the very concept of naming. We need consistency, and you can't have any meaningful level of consistency among names if names are too short.

To put it more generally, the more well-factored your code is, the greater is the danger of being too simple-minded. Breaking down code into short functions may be a good thing, but it's also another instance of Leaky Abstractions. The leak in case being the size of project vocabulary, and the need to be consistent, to distinguish, and write maintainable code.