A consistent naming convention is a key player in OOP (Object Oriented Programming) but it can certainly be extended to other paradigms.
Names serve the purpose of identifying elements.
Choose the wrong name and you will not identify a piece of code correctly, this costs time and money.
This is a simple guide to help you avoid this problem and get your code's quality a step higher.
Characteristics of good code naming:
Nameable elements classification:
My posts on Good Code are an introduction to a triad of concepts: Simple, Consistent and Readable code. Reading them takes a couple of minutes and will help you make the most this topic.
Example:
Usually good code is composed of other simpler pieces.
If these simpler pieces are not technical, then choose a contextual name.
Look at the elements inside this code element.
Is it context heavy or is it tech heavy?
Apply good naming on all languages for all the pieces that compose your code, from documents to variables and methods.
You can use it as a tool to discover code that needs simplification:
Choose the wrong name and you will not identify a piece of code correctly, this costs time and money.
This is a simple guide to help you avoid this problem and get your code's quality a step higher.
Characteristics of good code naming:
- Tells what it actually does or contains.
- Understandable with little contextual information.
- Consistent all over the application.
- Simple
Nameable elements classification:
- Physical
- Folders and Files
- Logical
- Classes, Methods
- Configuration, Documentation *
* Format and characteristics my change depending on the technologies used.
My posts on Good Code are an introduction to a triad of concepts: Simple, Consistent and Readable code. Reading them takes a couple of minutes and will help you make the most this topic.
Physical elements
- Physical elements are place holders for groups of elements or functionality.
I recommend using plural for directory or folder names.
For instance:
- The MVCApplication only contains files and folders related to the application.
- The Controllers folder contains only controller classes
- The Models folder contains only model classes
- The Views folder contains only view classes or files.
- The Views folder has a subdivision based on functionality, but still contains only views
Logical Elements
- Classes
Model only one object at a time therefore the name should be a noun or a noun phrase. - For instance: Car or CarPage
- Use the prefix "I" for interfaces. For instance: ICar or ICarPage
- Try to avoid generic words like Manager, Processor, Data or Info
- Methods
Methods represent actions or questions.
Names should indicate what action is been performed or the question been asked.
Building good method names
Never use one of the above alone. Always combine them.
Verb + Adjective + Noun + Structure
- Verbs
- Save, delete, notify, update, or generate, etc.
Sometimes you could use "process" but only for queues or other things of this nature.
Verbs that are clear on the meaning according to the context are also ok. - Adjective
- Find a balance between the number of parameters and the adjectives in the name.
Try not to use more than 3 parameters. - Noun
- The class or object being interacted with.
- Structure: (optional)
- Unique to the situation.
Example:
- GetGreenFruits()
- GetRedFruitsArray()
- GetFruitsList(Color desiredFruitsColor)
- GetFruits(DesiredFruitsClass desiredFruits)
Contextual Vs Technical naming
Usually good code is composed of other simpler pieces.
If these simpler pieces are not technical, then choose a contextual name.
Look at the elements inside this code element.
Is it context heavy or is it tech heavy?
private static void ValidateCompression(string input)
{
HuffmanTree huffmanTree = new HuffmanTree();
BitArray encoded = huffmanTree.Encode(input);
string decoded = huffmanTree.Decode(encoded);
PrintValidationResults(input, encoded, decoded);
Console.WriteLine("Valid compression: " + input.Equals(decoded));
}
//It is context heavy!
Is it context heavy or is it tech heavy?private ListCreateNodesList(Dictionary frequencies) { List nodesList = new List (); foreach (KeyValuePair symbol in frequencies) { nodesList.Add(new Node() { Symbol = symbol.Key, Frequency = symbol.Value }); } return nodesList; } //It is tech heavy!
Apply good naming on all languages for all the pieces that compose your code, from documents to variables and methods.
You can use it as a tool to discover code that needs simplification:
- If a method name has two verbs you need to split that method
- If the class has two strong nouns you need to split that class.
- If the directory has a generic name brake into several folders.
- And so on.
