Coding Style

Computer programs are not solely about getting stuff to work. They are largely about that, but not solely. It's also important for them to be clear and readable, because no one will want to use your code if they don't feel they can understand and maintain it. You're encouraged to read my longer essay on coding style.

For now, let the following list of rules and guidelines suffice:

  1. Don't explain the obvious.
  2. All names (functions, variable, modules, etc) should be descriptive and accurate.
  3. Be consistent with capitalization and punctuation. Decide on a scheme (say, CamelCase, or names_with_underlines) and stick to it. If there's a standard for your language, use it.
  4. Functions should do just one thing (suitably defined).
  5. Indentation is important. Code must be properly indented to show the syntactic structure of the program.
  6. A statement that belongs to (is part of) another statement should be indented relative to the containing statement. Statements that are at the same level in the syntax tree should be indented the same amount.
  7. Document the program as a whole. What does it do, and what are its inputs and outputs. Say who wrote it, and when.
  8. Document functions. Each function should be preceded by a brief paragraph explaining what it does, how it works (if necessary) and the meaning of its arguments and return values.
  9. Document variables and data members. Explain the purpose and use of the data and any non-obvious aspects of its implementation.
  10. Document any code that is not obvious.
  11. Use proper spelling and grammar, except when brevity is more important.
  12. Remember that screens and printers have finite width. Stick to an 80-character line.

Furthermore, good coding avoids redundancy and unnecessary duplication of code. This is sometimes known as the Don't Repeat Yourself (DRY) principle. While it can obviously be over-done, avoiding repetition means:

  • Code only has to be debugged in the one place it's defined, not in all the copies, and
  • Updates to the one copy of the code propagate to all the places its used.

For example, if you often need to zark some data, defining a function to zark the data and invoking it whenever necessary means that you can debug the zark function once, and if the requirements of the zark operation change, you can update the one function to effect the change. So, we'll add one more rule:

  1. Avoid redundancy and code repetition by looking for suitable opportunities for abstraction via functions, methods, modules and the like.

Finally, good coding should avoid security flaws. In this course, you must avoid the following errors:

  1. SQL injection attacks by using prepared queries as appropriate, and
  2. XSS attacks, by using encoding HTML special characters as appropriate.
  3. Race conditions by using locking or transactions as appropriate.

Time and Work

The following link has been updated for Fall 2022

Finally, when you have completed the assignment, make sure you fill out the Time and Work Fall 2022 That report is required.