1. Communicating in Code: Naming
Programming Studio, Fall 2017
Robert Lightfoot

2. Names We assign names throughout a program Give identity
Imply behavior/purpose
Provide recognition

3. What gets named? Variables Functions Types/classes Namespaces Macros
Source Files

4. Choosing Names Why are names like i, j, x, y, p, n, b used?
Sometimes there are naming conventions
If you work at a company that has an agreed convention, follow it!
But, there are several “wise” ideas to consider when choosing names.

5. Naming Considerations
Be sure it’s not a reserved name (Duh!)
Sometimes it’s easy to forget…
Make it informative
Keep it concise
Make it memorable
Make it pronounceable

6. Why is Good Naming Important?
Human brain’s storage capacity is practically limitless
Approximately 2.5 petabytes (~300 years worth of FHD video)
However, the ‘short term’ memory used during thinking and being creative is quite limited
Only 5 to 9 pieces of information (some studies show even less)
Therefore, we do not add anything to that small footprint
Make things as self-describing as possible and remember them only for a short time when necessary (i.e., using them in code)
Source:

7. Informative Names
Ideally, we want everything to be apparent from the name itself
The larger or more descriptive the name is, the better
However, long names are not easy to remember/reuse either
To resolve this conflict (long name vs short), we will take help from the “context” of the variable/function
The amount of information a name needs depends on its context/scope – understand it when seen
Use descriptive names for globals, short names for locals
Large routines/loops need more descriptive names
s = 0;
for (WhichGroup=0; WhichGroup<num; WhichGroup++) {
s += G[WhichGroup].n(); }
Do we really need to be this much descriptive?
What is the goal?
What on the world is this?
What are we doing again?

8. Informative Names
The amount of information a name needs depends on its scope – understand it when seen
Use descriptive names for global items, short names for local item
Large routines/loops need more descriptive names
nAnimals = 0;
for (i=0; i<NumAnimalGroups; i++) {
nAnimals += AnimalGroup[i].NumberInGroup(); }

9. Descriptive Names
Names should convey what it represents or does, unless obvious from context
Describe everything a routine does
Print() vs. PrintAndCloseFile()
Avoid meaningless or vague names
HandleData(), PerformAction(), etc.
Focus on the “what” instead of “how”
inputRecord vs employeeData

10. Descriptive Names Procedures: Active names
Verb followed by noun
AnotherStudent(s) vs. AddStudent(s)
Functions different: give return value
GetNumStudents() vs. numStudents()
Booleans: Be clear what is returned
checkEOF() vs. isEOF()

11. Consistent Names Key: Be Consistent!
nKids, numKids, num_kids, NumKids, nkids, Number_Kids, numberofkids
Write1stObject(), WriteSecondObject(), write_third_object()
averageSalary vs. salaryMinimum
open/close, first/last, old/new, min/max, etc.

12. Consistent Names CloseFile() vs. fclose()
Use related names for related operations
OpenFile():
CloseFile() vs. fclose()
open/close, first/last, old/new, min/max, etc.

13. Name Length Tradeoff between description and visual space
Moderate-length names tend to be best
8-20 characters
If a glance at the code seems like it has lots of short or lots of long names, use caution!
Scope plays a role
Rarely-used functions might be longer

14. Name Length
Taken from Code Complete 2nd Edition

15. Other Random Naming Considerations
Beware of “temp” variables
Sometimes indicates lack of understanding
Should be replaced with real names when possible
Be careful of reusing variable names
Be careful of overloading names
Avoid intentional misspellings
Consider pronunciation
People will end up “reading” your code

16. Conventions Lots of conventions out there
Conventions help convey information away from its definition
Very useful for larger groups/programs
Sometimes critical to large projects!
Examples:
Globals have initial capital letters
Constants are in ALL CAPS
Etc.

17. Common Naming Conventions
Beginning/ending with a p if a pointer
Starting with n for a number
i, j are integer indices
s is a string, c or ch are characters
Beginning with _ for private information, or reserved commands

18. Example: Hungarian Naming Convention
Base types:
wn Window
scr Screen Region
fon Font
ch Character
pa Paragraph
Eg: wnMain, scrUserWorkspace

19. Example: Hungarian Naming Convention
Prefixes
a array
c count
d difference between two variables
e element of array
g global variable
h handle
i index into array
e.g. iwnUserView = index into array of windows giving user views

20. Naming Conventions
Have to assume that others will follow the convention
Hungarian notation: confusing or helpful?
Always use a defined convention at your workplace
If no defined convention, use a common one, rather than your own creation
This goes for other style aspects besides naming…