Handbook

# Guidelines

# General recommendations

  • Follow the boy-scout rule: Always leave the code better than you found it.
  • Enable linters, vulnerability checkers, and static analyzers for your IDE.
  • Strive to improve the quality of the code while working with it. If a quick fix degrades the quality of your code, plan a refactoring.
  • Remember, your code should be understandable both to you and your colleagues.

Prefer composition over inheritance (opens new window).

  • Beware of creating reusable components from the very beginning. An extra layer of abstraction will complicate their use.
    • When you get some data from external sources (e.g., database, HTTP call, etc.), perform type checking right at the beginning. Ideally, it should be done inside the adapter. So when data comes out of the adapter, it should already be type checked.
  • Take care of exceptions. On the low level, catch them and rethrow some specific exception while logging a message with the error.

# Code comments

  • Write comments in English.
  • Add comments with information that is not obvious when reading the code, e.g., describe side effects.
  • High-level comments on a class/module should not describe implementation details. If the class has a separate interface, write comments in the interface.
  • Low-level comments describe the code and should answer the questions: "What?" and "Why?" and not "How?".
  • If a bug fix requires writing complex code, also include the issue number from ClickUp in the comment.
  • Update comments at the same time as the code; do not duplicate.

# Refactoring and Boy Scout Rule

TIP

The Boy Scout Rule is a programming principle that encourages developers to leave the code they work on in a better state than it was when they found it. This means that when you come across a piece of code that needs improvement or refactoring, you take the time to make those improvements, even if they are not directly related to the task you were assigned.

  • Try to make refactoring in a separate branch. That will make easier to review the changes.
  • When you come across code that needs improvement, take the time to make those improvements, even if they are not directly related to the task you were assigned.
  • Prioritize refactoring code that is frequently accessed or modified, or that has caused issues in the past.
  • Use code reviews as an opportunity to suggest and make improvements to the codebase.
  • Take the time to properly document code, especially if it is complex or may be difficult to understand in the future.
  • Remove duplicate or unnecessary code, and make sure that code is properly optimized for performance.
  • Use automated testing tools to ensure that your changes do not negatively impact other parts of the codebase.
  • If you can't apply refactoring immediately, add a TODO comment describing what should be changed and why.

# Git

  • Make and push commits regularly.
  • Commits to an upstream must have the Task ID. E.g., PROJ-5222 some comment. If you're working in a branch and later intend to use squash commits, you can omit adding the Task ID.
  • Use Present Simple tense for commit messages. E.g., PROJ-5522 some comment.
  • Read more about Git flow.

# Versioning

We follow SemVer 2.0 (opens new window) conventions.

+------- MAJOR version when you make incompatible API changes,
| +----- MINOR version when you add functionality in a backwards compatible manner, and
| | +--- PATCH version when you make backwards compatible bug fixes.
| | |
x.x.x

# Logging

  • The application must support logging levels though the environment variable LOG_LEVEL.
  • The application must send logs to the stdout and stderr.
  • All personal data and passwords must be filtered.

# Liveliness, readiness and startup probes

Each application must provide the following endpoints:

# Exporters

Exporter must provide the following metrics of the application:

  • up - 1 if the exporter is up, 0 otherwise.
  • scrape_duration_seconds - duration of the last scrape.

Optional:

  • scrape_error - 1 if the last scrape failed, 0 otherwise.
  • scrape_error_message - error message of the last scrape.
  • scrape_error_code - error code of the last scrape.
  • scrape_error_details - error details of the last scrape.
  • scrape_error_stacktrace - error stacktrace of the last scrape.
  • scrape_error_exception - error exception of the last scrape.
  • scrape_error_exception_message - error exception message of the last scrape.
  • scrape_error_exception_stacktrace - error exception stacktrace of the last scrape.
  • scrape_error_exception_cause - error exception cause of the last scrape.

Example of exporter endpoint:

# HELP up 1 if the exporter is up, 0 otherwise
# TYPE up gauge
up 1
# HELP scrape_duration_seconds duration of the last scrape
# TYPE scrape_duration_seconds gauge
scrape_duration_seconds 0.000000
# HELP scrape_error 1 if the last scrape failed, 0 otherwise
# TYPE scrape_error gauge
scrape_error 0
# HELP scrape_error_message error message of the last scrape
# TYPE scrape_error_message gauge
scrape_error_message ""

Read more about uploading metrics to Prometheus (opens new window).

← Pipelines →