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
• clear logic including not using goto and good exception processing
• 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 the 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
  • 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 shorter than 100 characters
• Include a comment at the top of each source file you submit giving basic information:

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

  This will allow identifying misplaced files.
• If numeric constants 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;
          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.
• Likewise, classes should have a clear purpose. If a class is responsible for lots of different things, then some of those responsibilities should be given to a different class.
• 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.
• 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: