Typespec style guidelines

Chat / Discussions
, ,
1

I’d like to propose a silly typespec discussion: what is your style guidelines for writing typespecs?

I mean, do you:

  • use parentheses (zero arity functions, types, etc)?
  • use private types?
  • add docs to your typespecs?

Browsing the “source of truth” (Elixir’s own code base) it seems types aren’t usually documented (for example here) and they don’t use parentheses except for external t() types and zero arity functions.

I haven’t seem libraries add docs to type definitions either. inch_ex does not cover this scenario also (I’m guessing by looking at Plug report).

Some types in the Erlang documentation have a comment (for example here), but usually people just don’t bother documenting it.

I know this is just a typical style discussion, but with a dialyzer task going in standard mix I’d like to know general opinion about this :slight_smile:

6 Likes
2

I do whatever the elixir formatter does.

Private types are to my knowledge, only really useful within opaque types. I don’t generally use them because most of my custom types are usually named versions of the basic types. When I define structs, I type them publicly because I think of that as public API. If I were unsure of how I wanted to structure a struct, I might choose to make it opaque in that situation, so that users would only use the module I provide to interact with it. In that case the structure of the struct would be encapsulated in the module’s functions. If I used types only in the definition of the struct, I’d make those private.

I’d say most of the time it’s pretty obvious what the type is from just the name or it’s underlying type. For example, I wouldn’t need an explanation for:

@type name :: String.t()
@type server :: pid()

That’s because that’s the way the elixir formatter formats them.

When someone suggested adding something related to typespecs to credo, I seem to remember rrrene mentioning he hadn’t looked much into typespecs yet. So, it’s not a big surprise. I also completely ignored them when I first started Elixir.

I think that’s a good example where the type is opaque, so you need to know how you can create one.

2 Likes
3

The formatter only demands parentheses when it is a foreigner type (defined in another module). Otherwise it won’t remove nor add parentheses in any other cases that I am aware of.

I agree that most types are self-explanatory when we are dealing with direct types (just alias of built-in types) like the ones you mention. But when you do h Jason.encode_to_iodata!/2 and we see this spec:

@spec encode_to_iodata!(term(), [encode_opt()]) :: iodata() | no_return()

It is not obvious what the encode_opt() is. Then we follow it with a t Jason.encode_opt() and get:

@type encode_opt() ::
        {:escape, escape()}
        | {:maps, maps()}
        | {:pretty, true | Jason.Formatter.opts()}

And then we keep digging to understand what escape is and so on. The typespecs for Jason are just one example where things aren’t that obvious at first sight IMHO. If we follow the maps definition it will be @type maps() :: :naive | :strict and I am not sure about the context anymore. What is a naive map here? Then that’s where I go after the source or something.

I mean, I mostly agree with your opinions. I just think that currently we are leaving more things undocumented than it would be good (including me) and was curious to see if others agree.