Welcome (back) to the fourth installment of Carp Patterns, my series on how to structure Carp code! Today we’re going to look at modules, one of the fundamental ways in which we structure our code.
I’m going to try to give an overview of how you might want to design your modules. I understand that the structure of your code and the design patterns you use more broadly feed into each other, and I can only give you the patterns that best fit my use cases. I want you to go out and experiment with different ways of layering and structuring your code if you’re excited to play around a bit after this!
Let’s have some fun with modules!
Where do modules come from?
First, let’s look at when and where we create modules to modularize our code.
Types and implicit modules
Every time you define a type, a module is also conceived. This module will share the type’s name and contain a constructor, getters and setters, and other utility functions.
This, together with the fact that you can use defmodule multiple times on the same module name, gives us the first design pattern: to write modules around our types. All functions that primarily operate on that type should go in the module named after the type, and they should take the type as their first argument, unless there is a good reason for them not to.
As an example, let’s consider the Map data type1. It is a regular Carp type, and it’s also a module containing all of the map-related functions, such as Map.get and Map.put for finding and putting elements into the Map, respectively. Ideally, there will never be a module called MapHelpers that contains all of the auxiliary functions the main implementation is missing, because any package can reach into the Map module and add to it. Thus, auxiliary modules are considered an anti-pattern, at least by me.
Topic modules
Another natural place where modules emerge are when you work on a topic. There might or might not be a type involved, but if there is it is mostly incidental to your actual end.
An example for this in the standard library is the Test module. It is used for unit testing. It does contain a State type, but that’s not what it’s about: you want to write tests for your code, and if you need a type to accomplish it then so be it2. The type is only part of the API because the functions in Test take and return it, but you’re not expected to manually work with it in any way.
Other modules might not have a type at all, such as Geometry, which sports a whole to functions, for converting from radians to degrees and vice versa.
Basically, topic modules are for all the functions that do not belong to a type. You don’t want to poluate the global namespace, so you put things in modules, or even submodules3.
Module annotations
When creating your module, you usually want to expose some functionality to the wider world. Thus, all functions in Carp are public by default. You can use annotations to limit their visibility and who can use them, though.
Anything that is exported should have a docstring associated with it. You can add these by using doc. If you want to learn more about documentation, check out my first post in this series!
Anything you don’t want to be seen should at least be annotated as hidden. This will prevent it from accidentally being rendered in your documentation. You can optionally also mark things as private, but beware that these functions then cannot be used in macros, since they run in the context of the calling code, i.e. outside of the module. So, if you don’t use macros, mark everything internal as private, but if you do, you might have to think about things a little more—it’s part of the burden of a macro-monger!
A special note for macros
A word of caution f you work with macros that work on modules: the symbols for modules that are also types resolve to types first in a dynamic context. You might for instance want to use s-expr to destructure a module, but this might not always work. Check out this example:
; defines a type T and a module
(deftype T)
; you can verify this by typing `:i T` in a REPL
(s-expr T) ; => (deftype T)
; in contrast, just defining a module
(defmodule M)
(s-expr M) ; => (defmodule M)s-expr.
So, even though T is both a module and a type in Figure 2, we can only get at the type part! This is a littler frustratring since, this also breaks dependent code in the Introspect module:
(Introspect.module? M) ; => true
(Introspect.module? T) ; => falsemodule? being wrong.
Of course this is unacceptable and will likely be fixed in the future, but for now this is what we have to work with.
Fin
As always, I hope this was an interesting dive into module in Carp. See you for the next—and last—installation of this series, on dependencies!
Footnotes
1. Fun fact: the current implementation of Map was written by yours truly, and it’s implemented in pure Carp. It’s a relatively simple but effective implementation, but I’d like to have another go at it at some point. You can check out the current version of the code here.
2. If the types of these modules are internal, as is the case for Test.State, you should probably make the type internal.
3 Usually, the module hierarchies in Carp are pretty flat, but they don’t have to be. I expect the hierarchies to grow deeper as the ecosystem grows.