Coding Conventions

Coding conventions are a set of guidelines for programmers to follow when writing source code. These conventions help make the source code more understandable and maintainable for others, or for the programmers themselves in the future.

These conventions apply to programming work organized by FIT-HCMUS (Faculty of Information Technology, University of Science, VNU-HCM) and cover both C++ and Python coursework. Each rule is illustrated with examples in both languages.

1. Variable Naming¶

• Use meaningful names that describe the purpose of the variables; variable names should be nouns. For example, to store the total price, use totalPrice (C++) or total_price (Python) instead of x or data.

  // C++
  int totalPrice = 100;

  # Python
  total_price = 100

  There are specific naming conventions for certain types of variables:

  • Boolean variables (which can only contain true/false values) should be named as Yes/No questions. For example: isValidUser, hasError (C++); is_valid_user, has_error (Python).

    // C++
    bool isValidUser = false;
    bool hasError = false;

    # Python
    is_valid_user = False
    has_error = False

  • Counter variables should use shorter names, such as i, j, or index.

    // C++
    for (int i = 0; i < n; i++)

    # Python
    for i in range(n):
        ...

  • Arrays, lists, etc. should be plural, to indicate that the variable contains multiple items. For example: userList, productPrices (C++); user_list, product_prices (Python).

    // C++
    std::vector<User> userList;

    # Python
    user_list = []
    product_prices = {}

  • Temporary variables, such as temp, should be used wisely.

• When naming variables, avoid abbreviations (except for common terms such as url), and limit overly long names — aim for a balance between brevity and clarity.

Some variable naming styles:

• camelCase: names start with a lowercase letter, and each subsequent word starts with an uppercase letter, without any separators. For example: userName, totalPrice.

• snake_case: all characters are lowercase, and words are separated by underscores. For example: user_name, total_price.

Remark: both camelCase and snake_case are acceptable in both languages, as long as the style is applied consistently. In Python materials, snake_case follows the PEP 8 recommendation; in C++ coursework, camelCase is the more common choice.

2. Function Naming¶

• Use meaningful names that describe the purpose of the functions; function names should be verbs. For example: calculateTotalPrice() (C++), calculate_total_price() (Python).

  // C++
  double calculateTotalPrice(int quantity, double unitPrice);

  # Python
  def calculate_total_price(quantity, unit_price):
      ...

• Function naming styles are the same as variable naming styles (see Section 1).

3. Naming Other Components¶

• Classes or structs: use the PascalCase style, where each word starts with an uppercase letter, with no spaces or underscores. For example: OrderController, ProductManager.

  // C++
  class OrderController { /* ... */ };
  struct ProductManager { /* ... */ };

  # Python
  class OrderController:
      ...
  
  class ProductManager:
      ...

• Constants: use the UPPER_SNAKE_CASE style, where all characters are uppercase and words are separated by underscores. For example: MAX_VALUE, PI, DEFAULT_TIME_OUT.

  // C++
  const int MAX_VALUE = 100;
  const double PI = 3.14159;
  const int DEFAULT_TIME_OUT = 30;

  # Python
  MAX_VALUE = 100
  PI = 3.14159
  DEFAULT_TIME_OUT = 30

4. Comments¶

Comments are text written alongside the source code to describe, explain, and provide information to the programmers and the readers. Comments are not executed when compiling and running. Each language provides its own comment types.

In C++:

• Single-line comments (//). For example:

  return fib(n - 1) + fib(n - 2); // Sum of the two previous Fibonacci numbers

• Block comments (/* ... */). For example:

  /*
   * Calculate the sum from 1 to n
   * Input: Integer n
   * Output: Sum from 1 to n
   */
  int calcSumUpTo(int n)
  {
      // ...
  }

In Python:

• Single-line comments (#). For example:

  return fib(n - 1) + fib(n - 2)  # Sum of the two previous Fibonacci numbers

• Docstrings (""" ... """), used to document functions, classes, and modules. For example:

  def calc_sum_up_to(n):
      """
      Calculate the sum from 1 to n
      Input: Integer n
      Output: Sum from 1 to n
      """
      ...

When using comments, the following conventions should be observed:

• Comment only when necessary; avoid excessive comments. Comment only complex or particularly meaningful code segments — straightforward and clear code does not need commenting.

• Comments should be concise but provide complete information, and should use consistent language.

5. Whitespace¶

Whitespace helps separate different components of statements and makes the code easier to read.

• Operators and operands must be separated by a space.

  Good:

  // C++
  int sum = a + b; // Add spaces before and after "+" and "="

  Bad:

  // C++
  int sum=a+b; // Lack of spaces makes it harder to read

  Good:

  # Python
  total = price * quantity

  Bad:

  # Python
  total=price*quantity

• Commas (,), colons (:), semicolons (;), etc., should be adjacent to the preceding component and followed by a space.

  Good (C++):

  for (int i = 1; i < n; i++)

  Bad (C++):

  for (int i = 1 ;i < n;i++)

  Good (Python) — the colon is adjacent to the preceding expression, and commas are followed by a space:

  if number % 2 == 0:
      print(a, b)
  point = {"x": 10, "y": 20}

  Bad (Python):

  if number % 2 == 0 :
      print(a ,b)
  point = {"x" : 10 , "y":20}

6. Indentation¶

Indentation is used to structure commands in the source code. There are two ways to indent — choose one style and apply it consistently:

• Spaces: use 2 or 4 spaces for each level of indentation (4 spaces is commonly used).

• Tabs: use one tab character for each level of indentation. Tabs must be used consistently in the source code, and mixing tabs and spaces must be avoided.

This also applies to Python, where indentation is syntactic — it determines the block structure of the code. PEP 8 recommends 4 spaces per level.

Here is an example of indentation in C++:

void checkEvenOdd(int number)
{
    // Indentation here
    if (number % 2 == 0)
        cout << number << " is even." << endl;  // Indentation here
    else
        cout << number << " is odd." << endl;   // Indentation here too
}

And the equivalent in Python:

def check_even_odd(number):
    # Indentation here
    if number % 2 == 0:
        print(number, "is even.")   # Indentation here
    else:
        print(number, "is odd.")    # Indentation here too

7. Bracing¶

In C++, braces ({}) are used to open and close blocks of statements (a collection of multiple statements) grouped into a logical unit. Two bracing styles are accepted — choose one style and apply it consistently:

• Style 1 — opening brace stays on the same line. The opening brace is on the same line as the condition or function declaration, and the closing brace is on a separate line after the block of statements ends.

  if (condition) {
      // Code
  } else {
      // Code
  }

  Advantage: optimizes space.

• Style 2 — braces are always placed on a new line.

  if (condition)
  {
      // Code
  }
  else
  {
      // Code
  }

  Advantage: clear and easy to read.

In Python, there are no braces: a block opens with a colon (:) and is defined by its indentation level (see Section 6). For example:

if condition:
    # Code
else:
    # Code

Body-less placeholders (for example, when a function is not yet implemented) should use the pass statement (or the ... stub literal) — never an empty braced block as in C++:

def not_implemented_yet():
    pass

References¶

1. FIT-HCMUS (2024). Overview of Programming Environment and C/C++ Coding Styles. Practice document.

2. Google C++ Style Guide. https://google.github.io/styleguide/cppguide.html

3. Monash University. Programming styles. https://www.monash.edu

4. PEP 8 — Style Guide for Python Code. https://peps.python.org/pep-0008/