SE 3800 Coding Standard

In addition to correctness, solutions will be graded for style and design. Additional detail is given below, but here are the key points:

• Use meaningful names for identifiers except those with very limited scope (such as the parameter for a one-line function).
• Format your programs consistently and nicely, including judicious use of spaces and blank lines. Keep line lengths to about 80 characters.
• Ensure your files contain no hard tabs.
• Include your name (prominently) in source files.
• Providing enough documentation that another person can understand the modules in your solution, without providing documentation that is blatently obvious from examining the code. For example, the first documentation is useful but the others are not:

    const int MAX_SIZE = 30; // max # of dates
    const int LIMIT = 50;    // limit of 50 – USELESS
    if ( x > 0 )             // check x is positive – USELESS
  

• Follow standard design principles including small subroutines, minimal repeated code, and tightly scoped identifiers.
• Fix your code so it builds without compilation warnings using C++17 and the -Wall option.
• Use lower case for repository, file, and other names unless a tool mandates a different convention.

More specifically:

• 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
    • havng 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
• 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];
  

  See below for a discussion of constants in tests.
  • Constants are to be written using SCREAMING_CAMEL_CASE.
  • Naming constants applies to just numeric constants. Character and string are already descriptive, 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.

Standards Specific to C and C++ Projects

• File names are to be all lower case. This ensures your projects will build on Unix as well as Windows.
• Use the extensions .cpp and .h for C++ sources.
• Use -Wall in your C and C++ builds (to generate all warnings) and ensure your code compiles with no warnings. In most cases, the warnings indicate issues that make your code unstable.
• Avoid C libraries in C++ programs. In particular, do not use printf, scanf, atoi, and other C functions in C++ code. Generally use std::string over C-style (null-terminated) strings.
• Follow the standard structure for header files:
  • Use #ifndef...#endif to ensure each header file is processed at most once in each compilation unit.
  • Do not include "using namespace XXX" declarations in header files.
  • The first include in an implementation (.cpp or .c) file needs to be the header file giving the interface. For instance, the first include for mycontainer.cpp must be mycontainer.h.
  • Include project-specific headers before standard headers; for instance, mycontainer.h before stdexcept.
  • Use forward declarations (such as class Money;) where possible to avoid including one header file in another.
  • If forward declarations do not work and a piece of code depends on a particular header, explicitly include that header. For example, if a class uses string, then #include <string> in the header file for that class, even though the header file might include other header files that also include string.
• Generally separate interfaces from implementations, but it is acceptable to define short, non-virtual methods in header files.
• In C++, use C++17 constructs where appropriate; for instance, use nullptr rather than NULL.

Note there is no rule that only one class appear in a particular source file.

Git Repositories

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

• Do not push build products. In particular, never push the Debug folder from Eclipse. Every Eclipse project should include a .gitignore with the content

  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.