A personal pain point of mine is when the examples just import TheModule exposing (..) rather than just using fully qualified references TheModule.aFunction .
First of all, because that's not how the library will be used. Second, and more important, unless you know already what the library exports, for every symbol you encounter you need to go through the whole example code to check whether it was declared in the example or it comes from the library: if you CANNOT find it in the example, then it means it comes from the library. The situation is even worse if the library exports more than a module and all are imported with (..). I think this unnecessarily increases the time and cognitive load required to understand a library (which is often times already a demanding task). On Monday, May 8, 2017 at 1:58:26 PM UTC+10, Matthieu Pizenberg wrote: > > Exploring a bit the packages repository, I've come accross the following > options: > > 1. no examples/ dir, all in readme and documentation. > (elm-array-exploration, ...) > 2. examples/ dir with nothing more than `.elm` files (elm-decode-pipeline, > elm-monocle, ...) > 3. examples/ dir with an `elm-package.json` file (elm-transducers, ...) > 4. examples/ dir with a `package.json` node builder (elm-kinto, ...) > > I personally have a mix of (2) and (3). However I feel like they all have > issues. > > 1. Sometimes, having a "ready to build" example is useful. > 2. It relies on building from the root directory of the package (where the > `elm-package.json` file lives). It also means that the example file can > "cheat" by accessing non exposed modules. > 3. If you add your `src/` dir in the json, then you can also "cheat" like > in 2. If you do not, and you use your package as if it was loaded from elm > packages, then you cannot verify that your latest modifications (not pushed > yet) are working with your examples. > 4. Well, it's a bit too heavy of a machinery most of the times. Plus it > also requires an `elm-package.json` file anyway so the same issues as (2) > and (3) apply. > > *Do you think there is a best practice? Are there alternatives to those > four?* > -- You received this message because you are subscribed to the Google Groups "Elm Discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to elm-discuss+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
