Wednesday, June 13, 2012

Naming your variables, methods guidelines (CS: Part 1)

We name variables, properties, methods, arguments, classes, namespaces, folders, files. Here are some simple naming guidelines:

1. Use Intention-Revealing names: The name of anything should answer all the big questions. It should reveal why it exists, what it does and how it should be used. If a name requires a comment then the name does not reveal its intent. e.g you should not use something like int a; // users count. instead use something like int currentUserCount; No comment required.
Also it is a good practice to create constant variables whenever you're using constant in methods. Such as instead of using condition like if(currentUserCount == 100) use if(currentUserCount == MAX_USER_COUNT) and create a constant MAX_USER_COUNT with 100 value.

2. Make Meaningful Distinctions: Sometimes you try to give same name to refer to two different things in the same scope but as compiler won't allow you to do it you try to do it by adding number series, noise words, misspelling just to satisfy compiler. But this is not a good practice. If names must be different then they should also mean something different.

3. Use Pronounceable Names: Coding in a team is like a social activity and you need to discuss your issues, approach with your colleagues. You should use pronounceable names in your code just in order to have a healthy discussion. Just imaging telling someone that "slcctrlct is incorrect in this module" instead of "switchlegControllerCount is incorrect in this module". This will surely help you instead of being part of a joke.

4. Use Searchable Names: Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text. One might easily find MAX_USER_COUNT instead of searching 100 everywhere in class. Likewise the name i is a poor choice for any variable for which a programmer might need to search. It is the most common letter and likely to show up in every passage of text.
The length of a name should correspond to the size of the scope
5. Avoid Hungarian Notation: Earlier we used to name our variable in hungarian notation like phoneString : a variable for phone of type string. But suppose we later change its type from string to PhoneNumber (which can be done very easily and quickly by IDE) then variable name would be same. Thus it would be
PhoneNumber phoneString; which has misleading information. So avoid these type of notations.

6. Naming Interfaces and their implementation: Consider you are creating a factory class which will provide you an object of particular type of instance. This factory will be an interface and will be implemented by a concrete class. So what should you name them? IObjectFactory or ObjectFactory. Well, it would be better to leave interfaces unadorned here. The preceding, I , so common in today's legacy wads, is a distraction at best and too much information at worst. We don't need to show users that we are using Interface for our factory class.

7. Class Names: Classes and objects should have noun or noun phrase names like customer, wikipage. Avoid words like Manager, Processor, Data or Info in the name of a class. A class name should not be a verb.

8. Method Names: Methods should have verb or verb phrase names like postUserClick, deletePage.

9. One word per concept: Avoid using the same word for two purposes. If you follow the "one word per concept" rule, you could end up with many classes that have, for example, an add method. As long as the parameter lists and return values of the various add methods are semantically equivalent, all is well.

10 Don't add gratuitous context. Say there is a particular feature developed by a developer named Ram then don't create any class like RamDiscoveringDevice.cs. Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.

Credits: Clean Code ebook

No comments:

Post a Comment