CMPT 120 - D300 - Introduction to Computing Science and Programming 1 - Spring 2024

Good Programming Style (GPS)

Guidelines

1. Descriptive Naming:
   • We must use descriptive file names for our programs, i.e., names that describe what each program does.
   • We must name our classes descriptively, i.e., use a name that describe the purpose of the class (what the class models).
   • We must use descriptive variable names, i.e., names that describe the purpose of each variable.
   • We must use descriptive function/methods names, i.e., names that describe what each function/method does.
2. Comments:
   • We must comment our code because comments allow people reading our programs to understand what our programs do. An easy way to do this is to transform the steps of our algorithm into comments.
   • We must have a header comment block at the very top of our program file and this header comment block must contain
     1. the name of our class/file
     2. the description of our class/progam contained in the file
     3. a class invariant (if appropriate)
     4. the name of the author -> us!
     5. the creation date or last modification date, whichever is the latest
3. User Interaction (or User Interface):
   • When prompting the user, we must give her/him clear and unambiguous instructions: the value to enter, the format of this value (if possible) and any other useful information such as the range of the value, etc...
   • The output the program produces must be labelled clearly.
4. Readability:
   • We must create code that is easy to read. One way to achieve this is by using indentation, blank lines and spaces.
5. Literal Values:
   • We must not "hard-code" literal values into our code but instead, assign these literal values to constants. We can also prompt the user for such values (such as a filename) which we then assign to variables.
6. Code:
   • We must not (as much as possible) repeat code fragments in our programs. Code fragments that are repeated throughout our program/class make modyfing our code difficult because we may need to make several times the same code modifications at different locations. In a nutshell, it is error-prone. Solution: encapsulate repeated code fragments into a function/method then call this function/method when your code requires this fucntionality.
   • In general, we should minimize the use of break, continue and exit(...) statements in conditional and iterative statements because they do not allow us to construct conditions properly.
   • However, using break in switch statements is fine.
7. Functions and methods:
   • A function/method must perform one main (well-defined) action, i.e., it must have one purpose. Its name must reflect its purpose.
8. Boolean Conditions:
   • The conditions of our iterative statements and our conditional statements are not 1, 0, true or false.
     • For example, we cannot write
       1. while true :
       2. while not false :
       because, in the above iterative statements, we did not write proper Boolean conditions. Proper Boolean conditions are composed of condition variable(s) that are modified within the loop such that the Boolean conditions eventually become false, hence terminating the execution of the iterative statement (loop). The literal values true and false cannot be modified, so when we use them as illustrated above, we create infinite loops which require statements such as break, exit(...), etc... to terminate, but as we saw above, we cannot make use of these statements.
     • On the other hand, we can write this:

       keepPlaying = true;
       while (keepPlaying)
          ...
          # player wants to stop playing
          keepPlaying = false;