View Source TypeCheck.Credo.Check.Readability.Specs (TypeCheck v0.13.7)

A custom Credo check which supports the @spec! syntax.

NOTE: This module is only compiled if you've added :credo as a (dev/test) dependency to your app.

To use this check in your project, make sure you have a .credo.exs config file (which you can generate with mix credo gen.config) and make sure to add it to the :checks :enabled list:

%{
  configs: [
    %{
      checks: %{
        enabled:
          [
            {Elixir.TypeCheck.Credo.Check.Readability.Specs, []},
            # ...
          ]
          # ...
        }
      # ...
    }
  ]
}

This check is an alternative to Credo's own experimental Credo.Check.Readability.Specs, so be sure to turn that check off.

Basics

This check is disabled by default.

Learn how to enable it via .credo.exs.

This check is tagged :controversial

This means that this check is more opinionated than others and not for everyone's taste.

This check has a base priority of 0 and works with any version of Elixir.

Explanation

Functions, callbacks and macros need typespecs.

Adding typespecs gives tools like Dialyzer and TypeCheck more information when performing checks for type errors in function calls and definitions. Typespecs will also be shown in generated documentation, and can be a great way to concisely convey how a function should be used.

Using TypeCheck's @spec! syntax which will also enable runtime type-checking: (Don't forget to use TypeCheck in your module!)

@spec! sub(integer, integer) :: integer
def sub(a, b), do: a + b

If you do not want runtime checks, write a normal @spec:

@spec add(integer, integer) :: integer
def add(a, b), do: a + b

Functions with multiple arities need to have a spec defined for each arity:

@spec! foo(integer) :: boolean
@spec! foo(integer, integer) :: boolean
def foo(a), do: a > 0
def foo(a, b), do: a > b

The check only considers whether the specification is present, it doesn't perform any actual type checking while reading your code.

Like all Readability issues, this one is not a technical concern. But you can improve the odds of others reading and liking your code by making it easier to follow.

Check-Specific Parameters

Use the following parameters to configure this check:

:include_defp

Include private functions.

This parameter defaults to false.

General Parameters

Like with all checks, general params can be applied.

Parameters can be configured via the .credo.exs config file.