SoftwareStandards

Software Standards

Overview

1. Overall, the simpler the code, the better. Writing a complex statement is usually not the best way to code. Writing two or three simple statements instead is much better.
2. Avoiding defaults is preferred. It saves little. Stating it instead of assuming it makes it explicit and easier for the next developer. In addition, defaults may vary based on the language. Developing a dependence on them is not good.
3. In most cases, a more readable code is preferred to code that optimizes at the statement level. This optimization can almost always be achieved by the compiler/interpreter. Therefore its benefit is minimal at the coding level. Readablity is essential for good code

Documentation

A properly documented software project includes the following:

1. Each source code file includes a header comment that includes:
   

           /********************************************************
            * Author:>  	author name>
   	 * Course:	course code (i.e. CSC 121)
   	 * Assignment:	assignment name
   	********************************************************/

   1. If the file is the main file, then the header should also include (before the ending stars) :

      	 * Problem:	short problem description

   2. Else it should include (before the ending stars):

      	 * Purpose:	short description as to the purpose of that file

2. Each variable that is not self-evident to an independent reader should have a comment indicating its purpose.
3. Each method that is non-trivial must have a single simple sentence stating its purpose. Trivial methods are defined as one line methods, or extremely obvious to the independent reader.
4. Any complex section of code, must have a comment explaining the logic

Style Requirements

No line should exceed 80 characters long unless absolutely necessary. This is to facilitate simple printing and easy of reading the code in most environments.

Soft tabs (not hard tabs) should be used to accurately allow for proper indentation in any environment.

Indentation that indicated level should be 4 spaces. Spacing used to line up arguments or to make long lines readable can be more.

No method/function (including comments) should be more than 66 lines long (except in extreme cases). This is to encourage proper modularilty of code.

White space should be used increase readability.

Field variables should only be used to store information between method calls.

Constants should be names entirely with uppercase letters and numbers

Class names must start with an uppercase letter and contain at least one lower case letter.

Variables and method/function numbers must start with a lowercase letter

Field variables should be labeled as private unless there is a specific reason to use another label.

Methods should be labeled public unless there is a good reason not to.

Only class constants should be accessible without using a access method outside of the class.

A class should contain the following by default:

1. At least one constructor
2. An accessor for each field variable
3. A modifier for each field variable that is allowed to change
4. Standard methods including: toString, equals, and possible compareTo

Field variables should only be initialized in constructors, never where declared.

While learning to program, no variable should be initialized in the same statement it is declared.

It should be extremely rare to declare variables inside a loop. Whenever possible, they should be declared outside of the loop and then reused inside.

Exiting a loop via a break should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.

Exiting a loop via a return should be rare and only executed in extreme conditions unless it is extremely awkward to code it any other way.

For loops should only be used in count controlled loops.

()’s should be used in complex boolean expressions (or arithmetic expressions) to increase readability even if they are not needed.