Software Engineering Guidelines

Source control

• We are using GitLab at FI MUNI.
• Every line of code must be tracked in a repository.
• Old, obsolete and deprecated code should be removed (it will be accessible in git history).
• The default branch is protected.
• Generated content should be gitignored (exceptions are possible).
• Merges are done using PRs.
  • PRs are properly described (the reasoning behing them). Ideally a link to a related issue is provided in the description.
  • PRs should be reasonably sized. They should deal with one issue / change / problem.
• At least one codeowner has to approve a PR before merging.
• Consistent branch naming.
• Every part of a repo should have at least two codeowners.

Commit best practices

• Commit messages are informative.
• Make small commits.
• Commit complete and well tested code.
• Don’t mix white space changes with functional code changes.

Code

• Every repo must have a README.md with basic documentation of repository structure, deployment, dev environment.
• Prefer standard library to a library to a framework.
• No trailing white space.
• EOL at EOF
• Secrets are stored in secured locations and not checked in to code.
• Issues are properly tracked (gitlab) and addressed in due time.
• Use unit testing, aim at 100% coverage.
• Use comments sparingly.
• Write platform-independent code.
• Minimize dependencies.

Python

• Use linting (black, with standard settings).
• Use mypy (or flake8).
• Use static typing hints.
• Prefer Python 3.8+
• Prefer unittest from std lib to pytest.
• Use conda / env so the dev environment is easily reproducible. (Describe it in README).

JavaScript

• Prefer TypeScript.
• Use eslint or similar.

Observability

• Significant events are tracked and related metrics collected if possible.
• Application faults and errors are logged.
• System is monitored (when running).
• Logging level is configurable.

Time management

• Work on one thing at a time.
• Consider using a tool like pomodoro timer, toggle, arbtt…
• Track your time for your own awareness.
• Try to estimate time for a code change, track it, see the discrepancy and try to improve the next time.

CI/CD

• To be added.