Hasker's CS 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
• include a banner comment at the top of each source file that includes your name and the assignment name
• document each class, function as discussed below; methods may need documentation as defined in the writeup
• minimal scope for variables
• methods, classes have clear purpose, generally 15 lines or less (including blank lines and comments)
• clear logic including not not exiting loops in the middle, using goto, good exception processing, and minimal dead code
• code compiles with no warnings

In more detail:

• 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 banner comment at the top of each source file you submit giving 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];
  

  • Constants are to be written using SCREAMING_CAMEL_CASE.
  • Note this applies to just numeric constants. Character and string constants already contain descriptions, and giving them names usually makes the code harder to understand.
  • Except in rare circumstances, do not declare named constants for test code to avoid creating maintenance problems. Tests are easier to understand if all of the data is local to the test, and the test documentation should be sufficient to understand the numeric values.
• 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.

Git Repositories

Some projects will require you to create Git repositories. Standards for these:

• Do not push build products. In particular, never push the build-Debug and related folders from Codelite. Every Codelite project should include a .gitignore with the content

  build-*
  

  This will capture the various builds, especially build-Debug.
• The repository name needs to be all lower case letters with no spaces. This facilites processing multiple repositories.

Note that using non-standard build tools generally leads to checking in build products by mistake. Use the approved build tools.

Note:

By default, Windows is configured to not show extensions such as ".cpp" for file names. This causes problems for engineering students. See here to enable showing extensions.