Hasker's SE 2040 Coding Standard

In addition to correctness, solutions will be graded for style and design. Detail is given below; but the quick list is

• meaningful identifiers
• format code nicely with spaces around operators and no tabs
• document each file as listed below
• document each class, function as discussed below
• minimal scope for variables
• methods, classes have clear purpose, generally 15 lines or less (including blank lines and comments)
• clear logic including not using goto, good exception processing, and minimal dead code
• code compiles with no warnings

• Use meaningful names for identifiers. One-letter names for loop variables is ok, but not method names or attributes.
• Format your programs consistently and nicely, including
  • ensuring there are no tab characters in your file
    • If you don't know how to fix this, ask!
  • ensuring that all indentation is consistent (2 to 4 spaces for each indentation, indenting to show flow of control)
  • indent comments with other code:

            // capture behavior common to all birds that swim
            public abstract class Waterfowl {
               // move in pattern typical for this type of bird
               public abstract void swim();
            }
    

  • using blank lines to separate methods and separate attributes from methods
  • adding spaces around binary arithmetic and logic operators such as *, +, <, ==, &&; for example x * y < a, not x*y<a
    • unary operators like ++, ! are not required to have spaces
    • no spaces around access operators, . and ->
  • one space after each comma; for example:

            public void printResults(String[] items, int first, int last,
                                     String key);
    

  • no spaces between method/function names and the paren
  • keeping lines (including comments!) shorter than 100 characters
• Include a comment at the top of each source file you submit giving basic information:

  // 
  // Course:     SE 2040
  // Term:       Spring 2018
  // Assignment: assignment name
  // Author:     your name
  //
  

  This will allow identifying misplaced files and also serves as a declaration that you wrote the code.
• If numeric constants appear in the problem description/requirements or are used in multiple places (such as the maximum length of a string), create a named constant for that number and use it appropriately. For example:

          const int BUFFER_SIZE = 50;     // max items to process
          double toProcess[BUFFER_SIZE];
  

  Except in rare circumstances, do not declare named constants for test code to avoid creating maintenance problems.
• Give all variables minimal scope. That is, give them no more visibility than necessary for the design. Variables which are local to a method should be declared within it, and attributes should private or protected. Use static and package scope for variables only when absolutely necessary. Global variables are to be avoided at all costs. Global and static constants are fine.
• Methods (aka functions) need to have a single purpose. For example, computing some result and printing it out in the same method is doing too much at once. Break such code into multiple methods/functions. Generally, no method/function should be longer than about 15 lines of code unless it has a switch statement in it, and even then the individual cases should be just one or two lines long. If you can justify a longer method, then you are probably fine, but look closely for ways to break long sections of code into smaller pieces. Comments and blank lines within functions are counted.
• Likewise, classes should have a clear purpose. In SE 2811 terms, it should have a well-defined set of responsibilities. Split classes that have a large number of responsibilities.
• Favor domain classes; that is, system designs should generally be built around classes that capture objects and concepts that appear in the problem description.
• Keep the flow of control obvious in methods. Do not use goto statements. Also, do not use exceptions for normal processing, such as using exceptions to handle empty containers.
  • Included in this: minimize the amount of dead code.
• Keep methods reasonably short and minimize repetition.
• If you catch an exception, deal with it in some reasonable fashion such as printing an error message and resuming processing. Never simply catch an exception and ignore it without a strong, documented reason.
• Document all classes and public methods other than simple getters and setters. In C++, document functions and public methods where they are declared.
• Feel free to document your code in ways beyond the minimum, but make sure your documentation adds information. Comments like

          distance += 10; // add ten to distance
  

  are worse than useless - don't write a comment if its opposite is obviously false.

Note: