Chapter 7. Code Quality Standards

Table of Contents

7.1. Motivation
7.2.1. Block Comments
7.2.2. Internal Comments
7.3. Formatting
7.4. Readability
7.4.1. Variables
7.4.2. Constants
7.5. Execution
7.6. Error Handling
7.7. Code Size
7.8. Structure and Subprograms
7.8.1. Modularity
7.8.2. Generality
7.8.3. Cohesiveness
7.8.4. Elegance
7.9. Homework

Assigned readings: This material is not in the textbook.

7.1. Motivation

Your primary goal in all programming endeavors should be to write code that is reusable without modification.

The purpose of coding standards is to make the code easy to read and understand, by other programmers, and by yourself after being away from it for a time.

Software specifications and evaluation criteria are generally categorized as function or non-functional. Functional criteria have to do with what the program is supposed to do (its function). The main question regarding functionality is whether it produces correct output given correct input. Non-functional criteria have to do with other qualities that are not apparent from the program's functionality. Is the code well documented? How efficient it is? There are hundreds of non-functional measures for software. A few of the most important ones are covered here.

The keys to readability are:

  • Modularity: Code is broken into sections that are completely independent of each other, so that you can understand a block of code without looking at any other code.
  • Cohesion: All code for a given task is in one block, with no other code intervening.
  • Consistency: Code is written and formatted in a consistent manner, so that it is easy to browse. You can see clear patterns in the structure and indentation, so that you can quickly scan the code and find what you're looking for.

Poor code quality can lead to a multiplicative increase in development cost as programmers waste time trying to decipher and debug it. As the project grows, so does the difficulty in dealing with poor quality code. Execution speed is also important, but don't sacrifice readability and intuitiveness for a marginal increase in speed.

Some of the standards in this document are universal truth, and others are arbitrary convention. You will encounter both kinds of standards in the programming profession (as well as some contradictions to universal truth). Each workplace has its own set of standards, which may conflict with each other and with this document. No two programmers will ever agree 100% on how code should be written and documented. It is more important that members of a team follow the same conventions, even though they may not agree with all of them, so that they can work effectively together. Accordingly, you will be graded on adherence to the standards described here, whether or not you completely agree with them. This will be good practice for your future career.

This document is a trivial example to introduce the concept of coding standards. When working for large organizations such as NASA, the FDA, or the military, coding standards may be hundreds of pages long. They will dictate how to format and document code, how to test code, how to document tests, how to secure code and test data, and much more.

Adherence to these standards could make the difference between an A and a B in the course. However, if your grade in this class is your only reason for writing good code, you should seriously reconsider studying computer science. The point of coding standards is to make you a more productive programmer. They will help you get programs done faster and lead to more efficient and reliable code. This will help you and others who work with your code in the future. This should be your primary motivation for following any standards.

Code quality is about half the grade for programming assignments and is based on the factors described below.