Credo rules you’ve been sleeping on

How to best setup Credo in your next Elixir project

What do you do when you start a new Phoenix project? If you’re like me, one of the first things you reach for is setting up your linting/static analysis stack. The crucial ones for my projects (and hopefully yours too) are:

But I’ve found that the defaults in Credo aren’t always my favorite. Here’s a couple things I recommend changing:

Enabling strict mode

Like TypeScript, Credo is much better off ran in strict mode. I don’t agree with everything in strict, but I just turn off the rules I don’t like. In return, you get a lot of nice rules that aren’t on by default.

I want to call out Credo.Check.Readability.WithCustomTaggedTuple as a particularly awesome rule that a lot of people are missing out on by not using strict. with is a very tricky thing that a lot of people misuse, and this rule helps push people in the right direction when using it.

Credo.Check.Design.AliasUsage is another really nice one that has a default priority of :normal.

There are a handful of rules marked both priority low, and :controversial (a tag for rules disabled by default, of which you’ll see at the bottom of your auto-generated .credo.exs file). I won’t really touch on those.

What I disable

First off, I really dislike Credo.Check.Readability.AliasOrder. I don’t really like spending the time to guess alphabetical order of imports in any programming language. I’m actually not a computer, I can’t really tell that sort of thing by reading them at a glance. If the formatter could do it that would be another thing.

There’s also one rule that’s not strict that I also turn off: Credo.Check.Design.TagTODO. I like TODO comments. I like leaving myself little messages. I get the idea, yes, this should go in a ticket tracker or something. It doesn’t always work out like that in the real world.

What I enable

This ones a must-have for me: Credo.Check.Warning.MixEnv. I’m not really sure why this one isn’t a default actually. It’s such a big problem in basically any project that’s going to use releases (which to be fair, is not everybody, but it’s a big enough problem that I think it probably should be a default).

Credo.Check.Refactor.PassAsyncInTestCases: I love this one. I’ve worked on a number of code bases that missed out on tests that could easily have been async.

Here’s one that’s both :low priority and marked :controversial: Credo.Check.Readability.StrictModuleLayout. This rule enforces a specific ordering of the keywords alias, require, use, and import. I always look at these blocks and struggle to come up with what order they should really be in. I’ve been messing around with the one myself lately: not 100% sold on it but I think its going in the right direction.

Honorable mention

I really like the idea of Credo.Check.Readability.ImplTrue, and I do it myself, but I’m not sure I’d want to force it on everyone else.

A simple config to start with

That all being said, here’s a little config you can try out if you like, or pull some of these enabled rules from :controversial: 

%{
  configs: [
    %{
      name: "default",
      files: %{
        included: [
          "lib/",
          "src/",
          "test/",
          "web/",
          "apps/*/lib/",
          "apps/*/src/",
          "apps/*/test/",
          "apps/*/web/"
        ],
        excluded: [~r"/_build/", ~r"/deps/", ~r"/node_modules/"]
      },
      plugins: [],
      requires: [],
      strict: true,
      parse_timeout: 5000,
      color: true,
      checks: %{
        enabled: [
          ## Consistency Checks
          {Credo.Check.Consistency.ExceptionNames, []},
          {Credo.Check.Consistency.LineEndings, []},
          {Credo.Check.Consistency.ParameterPatternMatching, []},
          {Credo.Check.Consistency.SpaceAroundOperators, []},
          {Credo.Check.Consistency.SpaceInParentheses, []},
          {Credo.Check.Consistency.TabsOrSpaces, []},

          ## Design Checks
          {Credo.Check.Design.AliasUsage,
           [priority: :low, if_nested_deeper_than: 2, if_called_more_often_than: 0]},
          {Credo.Check.Design.TagFIXME, []},
          {Credo.Check.Design.TagTODO, false},

          ## Readability Checks
          {Credo.Check.Readability.AliasOrder, false},
          {Credo.Check.Readability.FunctionNames, []},
          {Credo.Check.Readability.LargeNumbers, []},
          {Credo.Check.Readability.MaxLineLength, [priority: :low, max_length: 120]},
          {Credo.Check.Readability.ModuleAttributeNames, []},
          {Credo.Check.Readability.ModuleDoc, false},
          {Credo.Check.Readability.ModuleNames, []},
          {Credo.Check.Readability.ParenthesesInCondition, []},
          {Credo.Check.Readability.ParenthesesOnZeroArityDefs, []},
          {Credo.Check.Readability.PipeIntoAnonymousFunctions, []},
          {Credo.Check.Readability.PredicateFunctionNames, []},
          {Credo.Check.Readability.PreferImplicitTry, []},
          {Credo.Check.Readability.RedundantBlankLines, []},
          {Credo.Check.Readability.Semicolons, []},
          {Credo.Check.Readability.SpaceAfterCommas, []},
          {Credo.Check.Readability.StringSigils, []},
          {Credo.Check.Readability.TrailingBlankLine, []},
          {Credo.Check.Readability.TrailingWhiteSpace, []},
          {Credo.Check.Readability.UnnecessaryAliasExpansion, []},
          {Credo.Check.Readability.VariableNames, []},
          {Credo.Check.Readability.WithSingleClause, []},

          ## Refactoring Opportunities
          {Credo.Check.Refactor.Apply, []},
          {Credo.Check.Refactor.CondStatements, []},
          {Credo.Check.Refactor.CyclomaticComplexity, []},
          {Credo.Check.Refactor.FilterCount, []},
          {Credo.Check.Refactor.FilterFilter, []},
          {Credo.Check.Refactor.FunctionArity, [max_arity: 5]},
          {Credo.Check.Refactor.LongQuoteBlocks, []},
          {Credo.Check.Refactor.MapJoin, []},
          {Credo.Check.Refactor.MatchInCondition, []},
          {Credo.Check.Refactor.NegatedConditionsInUnless, []},
          {Credo.Check.Refactor.NegatedConditionsWithElse, []},
          {Credo.Check.Refactor.Nesting, []},
          {Credo.Check.Refactor.RedundantWithClauseResult, []},
          {Credo.Check.Refactor.RejectReject, []},
          {Credo.Check.Refactor.UnlessWithElse, []},
          {Credo.Check.Refactor.WithClauses, []},
          {Credo.Check.Refactor.UtcNowTruncate, []},

          ## Warnings
          {Credo.Check.Warning.ApplicationConfigInModuleAttribute, []},
          {Credo.Check.Warning.BoolOperationOnSameValues, []},
          {Credo.Check.Warning.Dbg, []},
          {Credo.Check.Warning.ExpensiveEmptyEnumCheck, []},
          {Credo.Check.Warning.IExPry, []},
          {Credo.Check.Warning.IoInspect, []},
          {Credo.Check.Warning.MissedMetadataKeyInLoggerConfig, []},
          {Credo.Check.Warning.OperationOnSameValues, []},
          {Credo.Check.Warning.OperationWithConstantResult, []},
          {Credo.Check.Warning.RaiseInsideRescue, []},
          {Credo.Check.Warning.SpecWithStruct, []},
          {Credo.Check.Warning.UnsafeExec, []},
          {Credo.Check.Warning.UnusedEnumOperation, []},
          {Credo.Check.Warning.UnusedFileOperation, []},
          {Credo.Check.Warning.UnusedKeywordOperation, []},
          {Credo.Check.Warning.UnusedListOperation, []},
          {Credo.Check.Warning.UnusedPathOperation, []},
          {Credo.Check.Warning.UnusedRegexOperation, []},
          {Credo.Check.Warning.UnusedStringOperation, []},
          {Credo.Check.Warning.UnusedTupleOperation, []},
          {Credo.Check.Warning.WrongTestFileExtension, []},

          ## Controversial rules turned on
          {Credo.Check.Warning.MixEnv, []},
          {Credo.Check.Consistency.MultiAliasImportRequireUse, []},
          {Credo.Check.Design.SkipTestWithoutComment, []},
          {Credo.Check.Readability.SeparateAliasRequire, []},
          {Credo.Check.Readability.WithCustomTaggedTuple, []},
          {Credo.Check.Refactor.IoPuts, []},
          {Credo.Check.Refactor.FilterReject, []},
          {Credo.Check.Refactor.MapMap, []},
          {Credo.Check.Refactor.NegatedIsNil, []},
          {Credo.Check.Refactor.PassAsyncInTestCases, []},
          {Credo.Check.Refactor.RejectFilter, []},
          {Credo.Check.Warning.MapGetUnsafePass, []}
        ],
        disabled: [
          # Controversial checks I leave off. But you can enable them if you want!
          {Credo.Check.Consistency.UnusedVariableNames, []},
          {Credo.Check.Design.DuplicatedCode, []},
          {Credo.Check.Design.SkipTestWithoutComment, []},
          {Credo.Check.Readability.AliasAs, []},
          {Credo.Check.Readability.BlockPipe, []},
          {Credo.Check.Readability.ImplTrue, []},
          {Credo.Check.Readability.MultiAlias, []},
          {Credo.Check.Readability.NestedFunctionCalls, []},
          {Credo.Check.Readability.OneArityFunctionInPipe, []},
          {Credo.Check.Readability.OnePipePerLine, []},
          {Credo.Check.Readability.SingleFunctionToBlockPipe, []},
          {Credo.Check.Readability.SinglePipe, []},
          {Credo.Check.Readability.Specs, []},
          {Credo.Check.Readability.StrictModuleLayout, []},
          {Credo.Check.Refactor.ABCSize, []},
          {Credo.Check.Refactor.AppendSingleItem, []},
          {Credo.Check.Refactor.DoubleBooleanNegation, []},
          {Credo.Check.Refactor.ModuleDependencies, []},
          {Credo.Check.Refactor.PipeChainStart, []},
          {Credo.Check.Refactor.VariableRebinding, []},
          {Credo.Check.Warning.LazyLogging, []},
          {Credo.Check.Warning.LeakyEnvironment, []},
          {Credo.Check.Warning.UnsafeToAtom, []}
        ]
      }
    }
  ]
}

This is a living document! I’ll keep this updated over time as I make some changes to my personal defaults. 🙂