elixir.md

Elixir coding standards

Style Guide

Trento follows the Credo style guide.

Linting

The linting is enforced by the credo tool locally and in the CI.

Use the .credo.exs template as a starting point for your project.

Additional rules and exceptions

• Private functions must appear after public functions in order of usage.

Static analysis

Dialyzer must be used to check for type correctness.

Please write specs @spec tags for all public functions and typespecs for defined types, to help Dialyzer doings its job.

Code smells

The Catalog of Elixir-specific Code Smells is a good reference for common code smells in Elixir.

CI

Please use the CI template as a starting point for your project.

Documentation

Use ExDoc to generate the documentation for the project.

Please add relevant documentation to @moduledoc and @doc attributes and make sure to run mix docs to check the generated documentation before submitting a PR.

Repositories that don't publish a package to Hex, should publish the generated documentation to GitHub pages using the generate-elixir-docs action.

Testing

Testing guidelines:

• Read Testing Elixir.

• Prefer factories over fixtures to create test data.

• Hook to Telemetry events of 3rd party packages to synchronize the test code. Find here a generic example and here another example based on AMQP connections.

• Mocks and explicit contracts

• Controller tests as integration tests (pre-Phoenix Context but still relevant)

Test coverage

Test coverage is enforced by coveralls.io. Please add excoveralls to the list of dependencies and setup mix.exs file as shown here:

def project do
  [
    app: :yourapp,
    version: "1.0.0",
    elixir: "~> 1.0.0",
    deps: deps(),
    test_coverage: [tool: ExCoveralls],
    preferred_cli_env: [
      coveralls: :test,
      "coveralls.github": :test
    ]
  ]
end

defp deps do
  [
    {:excoveralls, "~> 0.10", only: :test}
  ]
end

# If you have a custom mix task you can override the coveralls.github task
defp aliases do
  [
    "ecto.setup": ["ecto.create", "ecto.migrate", "run priv/repo/seeds.exs"],
    "ecto.reset": ["ecto.drop", "ecto.setup"],
    test: ["ecto.create --quiet", "ecto.migrate --quiet", "test"],
    "coveralls.github": ["ecto.create --quiet", "ecto.migrate --quiet", "coveralls.github"]
  ]
end

The CI template includes a step to upload the coverage report to coveralls.io.

Please refer to the coveralls notification documentation to allow coveralls to post comments with the coverage report in the PR.

Phoenix

Guidelines for applications using Phoenix:

• Use the Phoenix documentation as a starting point for your project.
• Always refer to the Ecto documentation.
• Start with generators when possible, as they give a reference for the directory structure and naming.
• Use realworld example app as a reference for the directory structure, naming and code organization in general.
• Instead of Router Path helpers, prefer using the full path in the tests (e.g. /api/rabbits) to test that the route is correct.
• Document APIs using OpenAPI, cast and validate operations in controllers using the provided plug, and test controllers using OpenAPISpex.TestAssertions.
• The CI template includes a step to generate the Swagger UI and publish it to GitHub pages. Please refer to this pr to configure the ApiSpec module so that it does not depend on a running Endpoint when generating the openapi.json file.