Why is it important to choose the correct name for classes, functions and variables

1. OR
WHAT’S IN A NAME ?
enum ONE_FOUR_FLAG {
ONE_FOUR_FLAG_1 = 1,
ONE_FOUR_FLAG_2 = 2,
ONE_FOUR_FLAG_3 = 3,
ONE_FOUR_FLAG_4 = 4,
};

2. WHY INVEST TIME IN NAMING ?
• Private functions and variables
• Benefits the maintainer
• Clearer meaning, leading to less bugs
• Easier debugging
• Namespaces, classes and public functions
• Benefits all users with easier reuse
• Benefits the maintainer with easier expanding
• Removes the need for costly API renaming and prototyping

3. USE INTENTION REVEALING NAMES
• A proper name is better than a comment
int d; // duration of operation,
// in days
int duration_days; // of operation
bool verify(Dimentions); // within limits
bool withinLimits(Dimentions);
bool initialized(Dimentions);

4. AVOID DISINFORMATION
• Avoid using common CS names
s = getSize(idList); // Is this a list<> container?
int idList[100]; // Nope… confusing, I‟d say
int idArray[100]; // Same problem here
int ids[100]; // An improvement
int idGroup[100]; // better still
list<int> idList; // A proper use of “list”
• Lower case L, upper case o
int a = l;
if ( O = l )
a = O1;
else
l = 01;

5. AVOID DISINFORMATION
• Avoid small changes in long names
class XYZControllerForEfficientHandlingOfStrings;
…
…
…
…
class XYZControllerForEfficientParsingOfStrings;

6. MAKE MEANINGFUL DISTINCTION
• Avoid adding meaningless ‘noise’ words
class Product; // Informative enough
class ProductData; // „noise‟ word Data
class ProductInfo; // Same deal
class ProductShipping; // Distinctive
class ProductInventory; // Distinctive

7. MAKE MEANINGFUL DISTINCTION
• Same goes for object names
struct MessageA {
Header hdr;
MsgBodyA data; // Really? Doesn‟t hdr
// contain data as well?
};
struct MessageA {
Header hdr;
MsgBodyA body;
};

8. USE PRONOUNCEABLE NAMES
class DtaRcrdA {
private Date crtymdhms;
private Date modymdhms;
private final String pszrt = “type_A”;
…
};
class Customer {
private Date creation_timestamp;
private Date modification_timestamp;
private final String recordType = “Customer”;
…
};

9. USE SEARCHABLE NAMES
• A variable named ‘e’ is hard to search for
• Also 30 Class types beginning with CTRL
• However, modern IDEs and their add-ons (Visual
Assist, ReSharper) make searching much easier.
• Still, the code will be more understandable if names
stand out without the assistance of external tools

10. AVOID MENTAL MAPPING
• Being able to remember a lot of variable names, is
no excuse for making it hard for those that can’t …
const char url[] = “http://www.google.com/index.html”;
char * r = getUrlFilePath(url); // ah… it‟s “index.html”
…
f = fopen(r); // what was r again?
char * starterWebPageName = getUrlFilePath(url);
f = fopen(starterWebPageName); // A bit clearer, isn‟t it?

11. USE NOUN AND VERB PHRASES
• Combine nouns and verbs
student.setName(“Mike”); // a good option
student.changeNameTo(“Mike”); // an actual phrase
• But not too much…
String name = person.getName();
String name = person.name();

12. DON’T BE CUTE
void holyHandGrenade();// One down, five to go
void deleteAll();

13. PICK ONE WORD PER CONCEPT
• Be consistent
addressList.push_front(address);
customers.add(customer);
groceries.insert(product);
cars.append(suv);
• STL/CLR can sometimes serve as a baseline
insert // 1 or more elements, at certain
// location
push_front, push_back // 1 element, front or back
remove // remove all that match
clear // clear container from all elements
• Even if you dislike STL, remember the 1st paragraph

14. AVOID ENCODINGS
class Carrier {
int iFreq_MHz_;
};
class Carrier {
float iFreq_MHz_; // Not true anymore…
};
class Carrier {
int freq_MHz_;
};
class Carrier {
float freq_MHz_; // Units are sufficient info
};

15. SOLUTION DOMAIN NAMES
• Use when low level concepts are a must
• Because solution domain names might confuse coders,
making it harder for them to re-use the code
• Examples:
• gpioMux.setControl(3);
• vme.writeWordBE(0x0122AAAB, 15);
• receiver.writeReg(DTO_REG, freq);

16. COMPUTER SCIENCE NAMES
• Include all programming language constructs
• Language building blocks, algorithms, containers
• Will be more understandable to other programmers
than solution domain names
• But, better to use problem domain names, when
applicable

17. PROBLEM DOMAIN NAMES
• Use when computer-science names are
unclear
policy.list.find(pair.first) != policy.list.end()
policy.covers(vehicle)
bool Policy::covers(Vehicle vehicle) {
return carList_.find(vehicle.id) !=
carList_.end();
}

18. MAKE CONTEXT MEANINGFUL
• Don’t add redundant prefixes
// Gas Station Delux application
class GSDStation; // Try typing G and using
class GSDCustomer; // auto-complete after 30
class GSDTanker; // more of these…
namespace GSD { // Gas Station Delux
class Station;
class Customer;
class Tanker;
…
}

19. MAKE CONTEXT MEANINGFUL
• Use short names when possible
class BillingAddress;
class ShippingAddress; // Is it any different?
class MACAddress; // Different indeed
class Address;
class MACAddress;
Address shippingAddress, billingAddress;
MACAddress purchasedNIC;

20. MAKE CONTEXT MEANINGFUL
• Use longer names for clarity
for ( int i = 1; i < num; i++ ) {
meetsCriteria[i] = true;
}
for ( int i = 2; i < num / 2; ++i ) {
int j = i + i;
while (j <= num) {
meetsCriteria[j] = false;
j += i;
}
}
for ( int i = 1; i < num; ++i ) {
if (meetsCriteria[i]) {
Console.WriteLine(i + " is prime");
}
}

21. MAKE CONTEXT MEANINGFUL
• Use longer names for clarity
for ( int primeCandidate = 1; primeCandidate < num; primeCandidate++ ){
meetsCriteria[primeCandidate] = true;
}
for ( int factor = 2; factor < num / 2; ++factor ) {
int factorableNumber = factor + factor;
while (factorableNumber <= num) {
meetsCriteria[factorableNumber] = false;
factorableNumber += factor;
}
}
for ( int primeCandidate = 1; primeCandidate < num; ++primeCandidate ){
if (meetsCriteria[primeCandidate]) {
Console.WriteLine(primeCandidate + " is prime");
}
}

22. HOW TO INVEST TIME IN NAMING
 Choose a name
 Does the name capture the idea behind a function or class?
 Does the name describe what is a function supposed to do?
 Does the name avoid implying what isn’t in a function’s to-do
list?
 Does the name capture all the responsibilities a class has?
 Does the name exclude tasks not required of the class?
 Does the name make unit-test code clearer?
 Ask co-worker to review the name
 If you got a single “No”, reiterate the above points

23. WHY INVEST TIME IN NAMING ?
• Private functions and variables
• Benefits the maintainer
• Clearer meaning, leading to less bugs
• Easier debugging
• Namespaces, classes and public functions
• Benefits all users with easier reuse
• Benefits the maintainer with easier expanding
• Removes the need for costly API renaming and prototyping

24. REMEMBER !!!
• Even if you don’t remember anything else from this
presentation…
Invest time in naming

25. WORK BASED ON
• The power of names, Glenn Vanderburg
• C# Coding Style Guide, Mike Kruger
• The poetry of function naming, Stephen Wolfram
blog
• https://class.stanford.edu/c4x/Engineering/CS144/a
sset/Naming.pdf