Read on Twitter
I've been thinking a lot about how to tell stories using technical artifacts over the past few years. Some areas of interest are:
Source code
Data structures
Type systems
Tests
Commit history https://twitter.com/jonomallanyk/status/1281340736483581955
Source code Data structures Type systems Tests Commit history https://twitter.com/jonomallanyk/status/1281340736483581955
People have long talked of "self-documenting code". While this may not be 100% achievable, you can still go a long way.
The "extract method" refactor is your friend here as you try and write much of your code in higher-level domain terms.
The "extract method" refactor is your friend here as you try and write much of your code in higher-level domain terms.
The design of data structures also tells a story. Here, eliminating invalid states goes a long way. Someone new to the code shouldn't ask "what happens when both these booleans are true" only to be told "oh, that will never happen".
This applies to databases too, not just code!
This applies to databases too, not just code!
If your language has a type system, that's yet another way to tell a story. A smell to avoid here is "primitive obsession". Expressing domain concepts as types means a better story for both computers and humans.
Contrast the following signatures:
Contrast the following signatures:
I explored various ways that the @elmlang types can be used to tell stories in this talk from @ElmInTheSpring
I'd argue that storytelling is one of the primary functions of a test. As with much storytelling, it's easy to leave out key details or confuse the auditor with irrelevant facts.
If a value affects the outcome of the test, it should probably be kept inline with the test.
If a value affects the outcome of the test, it should probably be kept inline with the test.
As an example, this article explores how #Ruby factories in test setup can help avoid irrelevant details and when they can hide important knowledge. https://thoughtbot.com/blog/why-factories
A project's commit history is another story you tell. Recently, I've been separating my refactors into standalone commits. It's either clean-up commit after the fact, or a "make the change easy" pre-work commit.
As a bonus, this plays nicely with git bisect!
As a bonus, this plays nicely with git bisect!
I was inspired by @t_kelly9's elm-conf talk last year on testing in Elm. She mentioned the power of telling story through multiple lenses. Types AND tests AND comments. Having multiple points of reference leads to better overall understanding.
