Should examples on package.elm-lang.org use qualified functions?

Request Feedback
1

Here is some perspective on examples on package.elm-lang.org! :heart:

The Dict documentation starts with a nice example:

import Dict exposing (Dict)

users : Dict String User
users =
  Dict.fromList
    [ ("Alice", User "Alice" 28 1.65)
    , ("Bob"  , User "Bob"   19 1.82)
    , ("Chuck", User "Chuck" 33 1.75)
    ]

type alias User =
  { name : String
  , age : Int
  , height : Float
  }

That looks like typical Elm code to me! Nice.

If you then scroll down a bit, you come to Dict.get:

animals = fromList [ ("Tom", Cat), ("Jerry", Mouse) ]

get "Tom"   animals == Just Cat
get "Jerry" animals == Just Mouse
get "Spike" animals == Nothing

This does not look like any typical Elm code in the wild!

In my opinion, examples should show the reader how to write their code. Otherwise they are bad examples.

I have written Elm for a couple of years now, but I do remember struggling with this as a beginner. After a while I learned to go into “documentation mode” where you mentally add for example Dict. in front of all “loose” functions you see. I still had to watch out for the default imports though.

Looking at examples and seeing patterns is what my brain is really good at, so good examples are important to me. Having to mentally translate the examples I see does not help. @aion on Slack agrees.

Here are some links that mention things that, to me, should apply to documentation examples and recommend them to use qualified imports:

Qualified imports are preferred.

There is an example that shows a typical use of the function.

Write helpful documentation with examples

Providing examples of common uses is extremely helpful. Do it! The standard libraries all make a point to have examples that show how one should be using those functions.

Also, make the documentation for the library itself helpful. Perhaps have an example that shows how to use many functions together, showcasing the API.

(Bold emphasis mine.)

I think there are cases where unqualified use is acceptable. Such as Html and Html.Attributes. Or elm/parser. In such cases I think the docs should use unqualified functions as well. Show the recommended use of the package.

@jfmengels mentioned on Slack that he uses qualified functions in docs for his packages, since he finds it clearer.

@ianmackenzie (who writes great documentation for his packages) seems to also use qualified functions in his examples. For instance: Length - elm-units 2.10.0

What do you think?

21 Likes
2

I fully support that style, I feel it adds to code clarity because it gives you some more context to go off of when reading code. We use it as the coding style at work too and it really helps in a larger codebase (~70k LOC).

We also quality the Html and Html.Attributes imports as well, usually using

import Html exposing (Html)
import Html.Attributes as Attributes
5 Likes
3

(We use qualified Html, too, at work.)

1 Like
4

My preference is to literally qualify All The things (besides default imports and elm-test).

I don’t just outlaw exposing (..) in my shop, I outlaw exposing anything but elm-test entirely.

“as” is still encouraged however. :slight_smile:

5

The only things I typically expose are types because Html.Html and such is kind of clunky.

4 Likes
6

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.