NSWI170 Computer Systems

Guidelines to write a better C/C++ code

all curses | next curse

Rule #0: Consistent naming

The Babel Curse: Chaos arises when every programmer speaks a different language
The Clarity Charm Counter-Spell: Use clear, English, consistently‑styled names so your code speaks with one voice

Naming consistency is a fundamental code quality principle in which all identifiers - variables, constants, functions, structures, and other symbols - are written in a unified, predictable style that reflects clear intent. In the context of this course, this means using English terminology, adhering to the framework’s naming conventions, and choosing descriptive, semantically meaningful names throughout the program. Clear and consistent naming forms the basis of readable, maintainable code: before addressing deeper structural or logical design issues, a program must “speak” with one coherent voice so that its purpose is immediately understandable. Without this clarity, every subsequent code quality practice becomes harder to apply, harder to reason about, and far less effective.

Motivation

• Names communicate intent: descriptive names let readers understand the purpose of variables and functions without additional comments.
• English is the de facto universal programming language: APIs, documentation, errors, and libraries use English terms, so aligning your identifiers avoids constant mental translation.
• Consistency reduces cognitive load: when names follow one style, you spend less time deciphering code and more time reasoning about logic.
• Better collaboration: teammates (= teachers and future you) can immediately understand what a variable or function represents.
• Avoids subtle errors: mixing conventions or languages makes it harder to see when two identifiers refer to different things or when one is misused.
• Improves maintainability: clear, consistent names make long term changes safer and less error prone.

Explanation

• Use English for all identifiers
  • Stick to English for variables, functions, constants, and structures.
  • Avoid mixing languages (čas, time, currCas, pocetButton) to prevent ambiguity and translation issues.
• Follow the team/framework’s naming conventions
  • Match the style used in course materials (e.g., ALL_CAPS for constants).
  • Do not mix multiple styles (ledState, Led_state, LEDState).
• Choose descriptive names that express purpose
  • Name things according to what they represent (buttonState, sensorValue).
  • Avoid vague terms like value, data, stuff, var1.
• Be consistent across your entire program
  • Use the same name for the same concept everywhere.
  • Keep symmetric naming for related operations (readSensor() ↔ writeSensor()).
• Use abbreviations only when widely understood
  • Acceptable: idx, i (in for-loops).
  • Avoid personal shorthand: mv, tmpx, dly.

Self-check

Are all my variable and function names in English?
Do all identifiers follow the same naming style consistent with my legacy code and the funshield library.
Would another student immediately understand what all names mean?

Example

// Inconsistent spacing
// Do NOT use personal abbreviations that are not widely understood
// Prefer descriptive names instead of saving a few letters
// Be consistent with naming used by the framework, i.e., constants with capitals
constexpr  int ButtonAr[3] = {BUTTON1_PIN ,BUTTON2_PIN ,BUTTON3_PIN };

// Do NOT mix multiple languages in identifiers;
// also avoid names that may have unintended meanings in English
constexpr  int PocetButt = sizeof(ButtonAr) / sizeof(ButtonAr[0]);

// Fixed spacing
// ButtonAr --> ButtonArray / Buttons: more descriptive naming
// (Plural usually implies a collection, such as an array)
// name constans with capitals to be constistent with the funshield library
constexpr int BUTTONS[3] = { BUTTON1_PIN, BUTTON2_PIN, BUTTON3_PIN };

// PocetButt --> ButtonsCount/NumberOfButtons/ButtonsSize
// Note: for consistency, you should name all the upcomming array sizes with postfix _COUNT
constexpr int BUTTONS_COUNT = sizeof(BUTTONS) / sizeof(BUTTONS[0]);