Naming Tips

naming-tips.md

Taken from Naming Tips.

• Do not name methods ProcessData(). You only get to use this method name once per career, because you should have been fired immediately afterwards. Be specific about what it's doing inside; call it ValidateUserCredentials or EliminateDuplicateRequests or ComputeAverageAge, etc.

• Use naming to help you design the program. Pretend there's a rule saying "you can never write a void function", then think about all the steps your program makes to transform input into output, then chose names for those steps so you could make a written sentence with them. These are now your function names and the sentence is your program's structure.

• If it's general, it better be generalized. If you name a class FilterCriteria but it's really used for filtering files then it should be called FileFilterCriteria, even if your program only works on files. FilterCriteria would be the name of an abstract class.

• Avoid discussing hard work. This is a matter of style, but in the above I used ValidateUserCredentials and EliminateDuplicateRequests, and yet that sounds like a lot of hard work. Consider naming functions that work on collections as if they were properties, like ValidatedUsers and DistinctRequests to make it sound as if the work has already been done. These could then be rewritten as dynamic properties and make the glue code easier to read, but also make you think differently: the program starts to feel more reactive and functional.

• Avoid class names that end with "Manager". They make you think of basic algorithms as if they were complicated black-boxes. "Management" is the statistical allocation of resources to minimize risk and improve performance, not sorting lists or keeping connections open. Consider SortedList or ConnectionPool.

• Avoid superlatives. SuperCollection, FlexiRecord, MegaListView, UltraResolver etc. are wrong. One day you'll create a new class that does one more thing, and then you'll go groping around for another superlative. After a while you won't remember which does what.

• Hungarian notation should encode meaning, not type. Hungarian notation--if you chose to use it at all--was meant to tell you about its intended use, not what its datatype is. Don't use intCounter or strFirstname, instead use usFirstname for unsafe user input, sFirstname for sanitized input, and things like that.

• Don't hide behind your names. Let's say you clean user input by converting it to UTF-8, normalizing entities and escaping the quote marks. Don't do this all in the Escape() method; you need a ToUTF8() method, a NormalizeEntities() method, and then an Escape() method. If you want the convenience of a single method that does it all then make sure it has a vague name that suggests it's doing many separate things, like SanitizeInput().

• Don't forget to have a vowel movement. "f u cn rd ths u cd b a cmptr prgrmmr". You'd also be wearing glasses after three years, and a nervous twitch after twelve (trust me). Don't be afraid to spell things out properly; this isn't the era of 40-character terminals anymore.

• Consistency, Consistency, Consistency. Merely being consistent replaces volumes of documentation and months of training--it's literally that powerful when applied to a company, department, or body of code. Your documentation can be more concise, and once a programmer has learned one program or module he can intuit all of them with little additional training.

• Don't be afraid to rename. Sometimes you'll realize your first choice of name was inappropriate, but if it isn't used in a published API then you should strongly consider renaming it even if your development environment doesn't make it easy.