Write a common check that will detect this order of annotations
@spec x()
@doc ""
def x()
And recommend to do this instead:
@doc ""
@spec x()
def x()
The type of this comment should be :actionable or :informative, not :essential.
This will mostly apply just to the city-office exercise, but in theory it's a common check. I was asked about this in a few mentoring sessions.
While technically it doesn't matter which one comes first, @spec or @doc, almost always @doc comes first. My personal interpretation is that it's because @spec depends on the function name and argument list, so that when it's as close to the function definition as possible, it's easier to check if it's correct and to later change both when the function changes.
I don't know if there are any more authoritative opinions on this anywhere that could give better reasons?
Make sure to test this well, with scenarios such as this one not triggering the error:
@doc ""
def x
@spec y
def y
And remember about other keywords: defmacro, defguard, and their private equivalents.
Write a common check that will detect this order of annotations
And recommend to do this instead:
The type of this comment should be
:actionableor:informative, not:essential.This will mostly apply just to the
city-officeexercise, but in theory it's a common check. I was asked about this in a few mentoring sessions.While technically it doesn't matter which one comes first,
@specor@doc, almost always@doccomes first. My personal interpretation is that it's because@specdepends on the function name and argument list, so that when it's as close to the function definition as possible, it's easier to check if it's correct and to later change both when the function changes.I don't know if there are any more authoritative opinions on this anywhere that could give better reasons?
Make sure to test this well, with scenarios such as this one not triggering the error:
And remember about other keywords:
defmacro,defguard, and their private equivalents.