CS 113 - Programming Languages

Programming Design Guide

You are expected to pay attention to your code organization. Your programming should adhere to the standards explained here. While some of the rules are due to convention, many more are pearls of wisdom distilled from solid software-engineering principles and all of them are essential for making your code readable and/or easy to maintain and modify/reuse. This document explains guiding principles. For more specific formatting rules please refer to the formatting guidelines.

Intentional Coding

  1. Every line of code should have a deliberate effect on your program. If you are not sure why a line is there, it shouldn't be. If your program stops working because you removed that line of code that you don't understand, you need to understand it before you put it back.
  2. Within a single program, do not copy-and-paste code, only to change a few details. Instead, declare a function parameterize it. Do copy and paste code (changing as needed) between programs.
  3. Use constants to avoid so-called magic numbers - numerical values that are scattered all over your program and are difficult to understand or modify.
  4. Do not debug by trying all combinations. If you (or the debugger) pinpointed a line that doesn't work, it is important to spend the time to understand why. The most valuable gain of programming proficiency happens right here. A bug is not truly fixed unless you
    1. understood why it happened in the first place
    2. understood why changing the code the way you did fixed it

Scoping and Encapsulation

  1. Declare variables in the smallest scope possible. That is, prefer local variables over global variables.
  2. Elixir and Go differ in their encapsulation approaches and are reasonably distinct from Java. Still, be inspired by Java encapsulation and attempt to achieve similar ends.

Data Structure Design

There is usually more than one way to store and represent data. Some general thoughts:
  1. Do not store the same thing more than once, or in more than one place.
  2. Choose the smallest storage so that the above is true and accomplishes your algorithmic goals. (Ie sometimes you need to store the same information in several places in order to change the time complexity of the task. For example, explicitly storing the number of items in a linked list can change some operations from O(n) to O(1).

Comments

Each languages has slightly different recommendations and norms for comments. In general, you can look at code samples posted on the class web site. I attempt to comment posted code in a manner consistent with common usage. In addition these sites give recommendations:

Naming Conventions

Like comments, each language has a common style. Generally, Java and Go both use camelCase for almost everything (except class names that use CamelCase and constants that use upper SNAKE_CASE). Elixir uses snake_case for most things except Module names which use CamelCase with an initial capital letter. Specifics for each language are below.