6. Implementation

6.1. Code

Todo

good code > good doc, early optimization trap, early abstraction trap, exception/error handling: (un)recoverable, (un)expected errors

Code guidelines and best practices.

General advices

  • Always KISS - Keep It Super Simple;
  • All source files must be written in English (variables, functions, classes, docstrings and etc). Only strings submitted to customers/users should be in in their native language (i18n/l10n);
  • A code well written is self documented;
  • Pay attention to the quality of your code using some indicators like cyclomatic complexity or the presence of some Bad Smell.

Coding Style

Coding style is a complex subject with lots of personal preferences and we believe that this preferences must be respected until the limit where it causes readability issues to other developers in our team and to keep some level of consistency on our code base.

Usually we use the coding style proposed by the community of an specific programming language, eg:

PEP-8 Customizations

We use most of the rules defined by PEP-8 except the rules that define the maximun line length. Instead of 80 characters we define a soft-limit in 120 characters. You are allowed to use more than 120 characters but use it with moderation.

Tests

Todo

expand this session (or move to a new chapter), describe some test patterns?

  • Unit test every function, method and class.
  • Integration tests should assert each part called using mocks or return checks.
  • Avoid using VCR-like mocking system. VCR-like libraries store credentials used for tests in fixture files and it creates a security breach. The fixtures created by them are strongly dependent of the API state, making it hard to update the test in the future.
  • We don’t use test coverage as a metric, but as a way to find use cases not tested.
  • Features with multiple layers should be tested on all layers (an API endpoint should have tests in the manager level (focused in the data) and API level (focused in correct HTTP usage)

Configuration

Todo

move this session to other chapter?

  • Configuration through environment variables: 12-factor configuration.
  • Avoid different configurations for each environment.
  • Decouple configurations with libraries like prettyconf.
  • Configurations should control only the software behaviour. Business logic configurations must be handled like system data; database-stored and configured through an administrative interface.
  • Configurations that frequently change are good candidates to leave configuration files.

Security

Todo

create a chapter specific for security?

  • Sensible and secret data must not be versioned with the code.
  • Always follow and apply security patches.
  • Dependencies must be kept up to date.
  • Only use known and tested security methods and systems.
  • Security measures shouldn’t be entangled with infrastructure.
  • Handle HTTP errors with static pages to avoid exploits.

Libraries and APIs

Todo

Informations are temporarily in Portuguese but it will be rewritten in English in final version of the document.

  • Devem ter changelog.
  • Mudar a versão (major) sempre que houver quebra de compatibilidade retroativa.
  • Manter a versão anterior dentro de um plano de “deprecation” definido previamente em cada projeto.
  • O modelo de versionamento deve ser adotado consistentemente em todas as APIs de um mesmo projeto.
  • Documentação
  • Todas as bibliotecas devem ser versionadas segundo as diretrizes de versionamento semântico http://semver.org/ ignorando apenas os sufixos como: pre, rc, alpha.
    • Formato major.minor.patch;
    • Todas as alterações devem ser acompanhadas pela atualização da versão.
  • Manutenção de Changelog atualizado.

6.2. E-Mail

Todo

write this

6.3. Database

Todo

write this

non-sequential ids, strings instead of enums