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

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

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

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.

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

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: https://blog.synap.ac/10-surprising-facts-about-your-memory/

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?

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

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

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

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.

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

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

Name Length Taken from Code Complete 2nd Edition

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

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.

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

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

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

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…