Skip to main content

Good Programming Practices

Good Programming Practices

Points for programming assignments are awarded for error-free compilation, correct program output, and overall program structure. The program structure grade is an evaluation of the quality of your code. This includes the following:

  • Your code should have a clear, logical organization. Functions should be written as appropriate to break up the program. Don't put all of your code in the main function. In general, each function should easily fit on a single screen and have a clear purpose.

  • Variable names and function names should be intuitive and meaningful. For example, if you need a variable to represent an employee's salary, use the name salary, not x.

  • Use sufficient comments to describe functions and significant sections of code. These don't have to be long and involved. Keep them short and clear. Remember, comments are your opportunity to explain your logic to the TAs. But comments are also a important piece of documentation for all software, to help future developers maintain and extend the code. (See examples below.)

  • Use a consistent, logical method of indentation to make your program easy to read. For example, code inside a loop or if-else condition should be indented all at the same level (until reaching the inside of a nested loop or nested if-else construct).

  • Don't type lines of text that are too wide to fit a typical text screen window (generally no more than 80-90 characters maximum). Break statements cleanly across multiple lines as needed.

  • Avoid the use of global variables. Global constants are generally fine.

  • Follow all instructions for the specific assignment about data structures required/not allowed, new class declarations, and use/modification of provided code.

Use the example code given in class, in lab, and in the textbooks as guidelines. Programs that are unclear and do not compile will earn little or no credit.

Program correctness will be determined by evaluating your program on a series of test data sets. We will make available some but not all of this data, along with sample output, prior to the assignment due date. This will help you judge the quality of your program, but will not guarantee correct results on all data. You will need to ensure this on your own by creating additional test cases.

See also:  

Examples of Commenting

Most functions should have at least one comment (usually at the top) explaining what the function does. And functions of more than a couple lines should have addtional comments explaining the logic within the function body. Of course, in some situations, a function does not need comments (when the function's behaviour is obvious).

We suggest you avoid adding comments that do not help in the understanding of the program. For example: 

  string getNameOfRecipe() { // function that gets the name of the recipe

  }

The comment above is not useful (it is obvious that getNameOfRecipe() is a function and it is obvious that it returns the name of the recipe). However, if the name of the function was getNR() it would be useful to add comments explaining that this function returns the name of the recipe. NOTE: It is better to use a descriptive name for the function than rely on comments!

Another example: 

  double getRoot(double a,double b, double c) { // get root function
    double d; // declare d as a double
    d = b*b - 4*a*c;
    double root = (-b + sqrt( d ))/(2*a); // compute the root
    return root; // return the result
  }

The comments above are also not useful (it is obvious that the return statement returns something; it is obvious that this is the "get root function").

Here is a much more informative commenting of the same code: 

  // This functions receives the coefficients of an equation in the form
  // ax2+bx+c=0 and returns one of its roots.
  // Attention:  We assume that the equation has at least one real root.
  double getRoot(double a,double b, double c) {
    double delta = b*b - 4*a*c;
    // We use Bhaskara's formula to compute one of the roots
    double root =  (-b + sqrt( delta ))/(2*a); 
    return root;
  }

 

See also the main Course Grades page, the and the Programming Advice from TAs page for more information.