/py-template

Template for a new python project

Primary LanguagePythonMIT LicenseMIT

py-template

This repository serves as a template for new python projects and a way to express best practices

Best Practices - Coding Practices

User input

  • Always use argparse for command-line arguments
  • Assume the use of yaml for structured input files unless there are compelling reasons for something else

User output

  • Always use logger for status output
  • Carefully choose an output format for standard formats, considering the following in order of priority:

Modularity

if __name__ == "__main__":
    do_main_task()

Testing

  • Always use pytest for testing
  • Introduce a simple continuous integration (CI) action ASAP

Collaboration

  • Generate pull requests (PRs) with as little code change as possible
  • Include tests in all PRs
  • Do not merge your own PR; there should always be at least one review by a non-author, and a non-author should merge

Packaging and installation

  • Introduce a pyproject.toml file ASAP

Best Practices - Style

Code formatting

  • Follow PEP8 style guide, ideally with a tools like black to help enforce it, especially via a plugin to your editor

Variable naming

  • Generally, choose nouns for variables and verbs for methods
  • Clear variable and method names can reduce the need for comments

Comments

  • Include a docstring in every method
  • Rely on clear variable and method names and add comments sparingly where the intent/approach is non-intuitive

Modularity

  • If you have cut & paste code in two different places, it probably should be a method
  • Even very short methods can be valuable if the method name makes the code more readable
  • Ideally, methods should be no longer than one screen worth of lines