# Style rules for type annotation?

**URL:** <https://discourse.julialang.org/t/style-rules-for-type-annotation/47788>\
**Category:** New to Julia\
**Created:** [October 5, 2020, 2:12pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788 "2020-10-05T14:12:41Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![Landrum](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/landrum/32/18330_2.png) [@Landrum](https://discourse.julialang.org/u/Landrum)\
**Post date:** [October 5, 2020, 2:12pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/1 "2020-10-05T14:12:41Z")

</div>

I’m reading the source of [Javis.jl](https://github.com/Wikunia/Javis.jl) right now, and I see that function docstrings have type annotations for arguments, but the arguments themselves are not explicitly typed. If the type of the argument is going to be given in the docstring anyways, why not just do `f(x::Number) = x^2` (with appropriate docstring) instead of something like

```julia
"""
    f(x)
Get the square of a number 'x'

# Arguments
- 'x::Number': The number to be squared

# Returns
- 'Number': The square of the input
"""
f(x) = x^2

```

It seems like if it’s possible to annotate the type in the function definition such that it would be annotated in the docstring, for the sake of readability and optimization, it should be. It’s possible this has something to do with the package being “under heavy development”, but under what circumstances is it appropriate to assert types in the function definition when they’re annotated in the docstring?

---

<div class="post-metadata">

**Author:** ![jling](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jling/32/212909_2.png) [@jling](https://discourse.julialang.org/u/jling)\
**Post date:** [October 5, 2020, 2:14pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/2 "2020-10-05T14:14:34Z")

</div>

> [@Landrum](#):
>
> why not just do `f(x::Number) = x^2` (with appropriate docstring) instead of something like

yes,

> <https://github.com/JuliaLang/julia/blob/8519538bb7bead5131c6c76ea31c5ccebde8de25/stdlib/Dates/src/periods.jl#L4-L10>

it’s just Javis picked that style

---

<div class="post-metadata">

**Author:** ![rdeits](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rdeits/32/286_2.png) [@rdeits](https://discourse.julialang.org/u/rdeits)\
**Post date:** [October 5, 2020, 2:34pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/3 "2020-10-05T14:34:13Z")

</div>

`TYPEDSIGNATURES` from [DocStringExtensions](https://juliadocs.github.io/DocStringExtensions.jl/stable/#DocStringExtensions.TYPEDSIGNATURES) makes it pretty easy to auto-generate these kinds of annotated docstrings in exactly the way you’re asking for:

```julia
julia> """
       $(TYPEDSIGNATURES)

       Do something cool!
       """
       foo(x::Number) = x + 1
foo

help?> foo
search: foo floor pointer_from_objref OverflowError RoundFromZero unsafe_copyto! functionloc StackOverflowError @functionloc OutOfMemoryError UndefKeywordError unsafe_pointer_to_objref

  foo(x::Number) -> Any
  

  Do something cool!

```

Note how the `x::Number` has been automatically extracted from the method definition and inserted into the docstring.

---

<div class="post-metadata">

**Author:** ![Mason](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mason/32/2423_2.png) [@Mason](https://discourse.julialang.org/u/Mason)\
**Post date:** [October 5, 2020, 2:49pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/4 "2020-10-05T14:49:11Z")

</div>

> [@Landrum](#):
>
> If the type of the argument is going to be given in the docstring anyways, why not just do `f(x::Number) = x^2` (with appropriate docstring) instead of something like

Just to give a counter-point, it’s often useful to just not restrict method signatures unless you actually have a reason to. The docstring is telling you it expects to get numbers, but maybe you can stick a square matrix in there and it’ll be okay, or even a string:

```julia
julia> f(rand(2,2))
2×2 Array{Float64,2}:
 0.754887 0.527028
 0.932377 0.654844

julia> f("hi")
"hihi"

```

---

<div class="post-metadata">

**Author:** ![Landrum](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/landrum/32/18330_2.png) [@Landrum](https://discourse.julialang.org/u/Landrum)\
**Post date:** [October 5, 2020, 4:12pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/5 "2020-10-05T16:12:08Z")

</div>

That makes sense and it is one of the strengths of Julia. I made a habit of annotating methods unless they were deliberately type agnostic in my own code and was thrown by the documentation-only annotation because it seems less efficient to compile, but I see the value in assuming methods will be used responsibly for the sake of fast, flexible development.

---

<div class="post-metadata">

**Author:** ![Mason](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mason/32/2423_2.png) [@Mason](https://discourse.julialang.org/u/Mason)\
**Post date:** [October 5, 2020, 4:17pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/6 "2020-10-05T16:17:12Z")

</div>

> [@Landrum](#):
>
> thrown by the documentation-only annotation because it seems less efficient to compile

Just a side note, there is no difference in the efficiency at compile time or runtime for these functions if you put type constraints or not. Type annotations in Julia methods are purely for dispatch.

This is different from almost every other optionally typed, JIT compiled dynamic language, so it’s a constant source of confusion.

---

<div class="post-metadata">

**Author:** ![cstjean](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cstjean/32/1444_2.png) [@cstjean](https://discourse.julialang.org/u/cstjean)\
**Post date:** [October 5, 2020, 4:29pm UTC](https://discourse.julialang.org/t/style-rules-for-type-annotation/47788/7 "2020-10-05T16:29:18Z")

</div>

> [@Mason](#):
>
> it’s often useful to just not restrict method signatures unless you actually have a reason to

Yeah, but then errors are caught later, if at all. I use `f(x) = x^2` in generic open source library code, and `f(x::Number) = x^2` in my end-user private code when I don’t expect to use a matrix. I can always change it later, and it’s better documentation.

Along those lines, I also started using `Any` type aliases for documentation. Eg.

```julia
const Functor = Any
run_with_context(f::Functor, ctx, ...) = ...

```

It makes the code clearer, until Julia starts supporting interfaces/contracts/etc.