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,

};

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

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);

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;

AVOID DISINFORMATION

• Avoid small changes in long names class XYZControllerForEfficientHandlingOfStrings;

…

…

…

…

class XYZControllerForEfficientParsingOfStrings;

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

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;

};

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”;

…

};

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

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?

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();

DON’T BE CUTE

void holyHandGrenade(); // One down, five to go

void deleteAll();

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

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

};

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);

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

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();

}

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;

…

}

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;

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");

}

}

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");

}

}

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

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

REMEMBER !!!

• Even if you don’t remember anything else from this

presentation…

Invest time in naming

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