Hasker's CS 2400 Coding Standard

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

• meaningful identifier names
• format code to Python standards, including no hard tabs
• document each file as listed below
• document each class, method, or function to Python standards
• minimal scope for variables
• methods, classes have clear purpose, generally 15 lines or less (including blank lines and comments)
• clear logic, good exception processing, and minimal dead code

More specifically,

• 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 that all indentation is consistent (2 to 4 spaces for each indentation, indenting to show flow of control)
  • using blank lines to separate methods and separate attributes from methods
    • However, do not use random blank lines within methods. If you need the blank lines to separate sections of code, give those sections (non-public) names. These names can be really long if that helps!
  • adding spaces around binary arithmetic and logic operators such as *, +, <, ==, &&; for example x * y < a, not x*y<a
    • unary operators like -x and ! are not required to have spaces
    • no spaces around the access operator, .
  • one space after each comma; for example:

            printResults(items, first, last, 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:     CS 2400
  # Term:       Spring 2020
  # 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:

          BUFFER_SIZE = 50;     // max items to process
          for ix in range(BUFFER_SIZE):
              print(ix)
  

  • Constants are to be written using SCREAMING_CAMEL_CASE.
  • Except in rare circumstances, do not create 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.
  • 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.
• Give all variables minimal scope. That is, give them no more visibility than necessary for the design. Use @property for read-only attributes and make them protected (_x) or private (__x). Particularly avoid global variables.
• 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 exceptions for normal processing, such as using exceptions to handle empty containers. 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, public methods other than simple getters and setters, and any stand-alone functions. Documentation is to be in the standard location for Python, after the method or function name.
• 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:

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