Refactoring guidelines

[BramDr]

Guidelines for refactoring PCR-GLOBWB.

Planning

• Create design diagrams before refactoring
  • Should include classes and their purpose
  • Should include interactions between classes through (public) function calls
• Create a GitHub issue for the specific refactor (see the contributing document)

Structure

• Modules and classes should be designed to be closed for modification but open for extension
• Modules and classes should be independent (i.e. avoid interactions between classes)
• Avoid methods not in a class (i.e. static methods)
• Class methods should be small, with a maximum of two to three indentations, and have a specific purpose
• Class variables are allocated during __init__()
• Avoid class variable modification in deeper sub-functions

Styling

• Code styling mainly follows the Python PEP8 specifications
  • Classes use TitleCase whereas properties/methods (and others) use snake_case
  • A leading underscore is used for private properties/methods
  • Avoid try-except block. If necessary, specify the exception expected
  • Prefer with block instead of calling 'close()'
  • Annotate all functions with the expected types (type-hinting)
  • Place (independent) classes and functions in separate files
• Before publishing a refactor, format your code using isort (for imports) and black (for code).
  • Consider using a git pre-commit hook to do so automatically