For a few years I ran these as a hobby business. The original idea was simple: let people search for UK companies within a given radius of a postcode. From there it grew to let you filter by SIC code, by company status — active, dissolved, and so on — and the whole dataset was kept up to date in real time as new companies were registered and existing ones changed. People used it for sales prospecting, for research, and for keeping an eye on particular corners of the market.

I enjoyed building it, and it taught me a lot about working with company data at scale. But it was always a side project, and my attention is needed elsewhere. Rather than let it limp along half-maintained, I’d rather close it cleanly.

So that’s that. Thank you to everyone who used it over the years.

If you need this kind of thing

The product is gone, but the expertise isn’t. If you need custom software built — particularly anything involving UK company data, Companies House, or turning a messy public dataset into something fast and searchable, I may be able to help.

Email me at jezen@jezenthomas.com for a virtual coffee and software chat.

100% test coverage is not enough. Here’s an example as to why in Python:

def division(x, y):
 return x / y

If you pass in 0 for y, it’ll raise an error. You have to know to test for the value specifically. Test coverage won’t save you here. With 100% line coverage or branch coverages, it won’t be found. That’s how 100% test coverage is not enough.

So, if test coverage is not enough, what can we do here?

Well, at least a couple of things.

Surfacing Failure Cases Automatically

It wouldn’t be sensible to try testing our division function against every possible input, because the set of possible inputs is effectively unbounded. Fortunately, we don’t have to. We can instead use a property-based testing library like hedgehog to generate inputs to our division function and show us the minimal way to reproduce an error when it occurs.

This example is in Haskell, and only accounts for integral numbers. Otherwise, it’s a near enough direct translation of the Python version.

import Hedgehog
import Hedgehog.Gen qualified as Gen
import Hedgehog.Range qualified as Range

division x y = x `div` y

prop_division_identity = property $ do
  x <- forAll $ Gen.int Range.linearBounded
  y <- forAll $ Gen.int Range.linearBounded
  let q = division x y -- quotient
      r = x `mod` y    -- remainder
  q * y + r === x

We’re relying on the integer division law to test our function.

The integer division law says:

When you divide one whole number by another, you get a quotient and a remainder. If you multiply the quotient by the divisor, then add the remainder, you get back the original number.

This law holds for divisor ≠ 0.

So, the test generates a range of integers, applies the division function to them, and checks that the result always adheres to the integer division law.

Running this in GHCi quickly surfaces the problem.

━━━ Main ━━━
  ✗ prop_division_identity failed at div.hs:15:13
    after 1 test.
    shrink path: 1:

       ┏━━ div.hs ━━━
    10 ┃ prop_division_identity = property $ do
    11 ┃   x <- forAll $ Gen.int Range.linearBounded
       ┃   │ 0
    12 ┃   y <- forAll $ Gen.int Range.linearBounded
       ┃   │ 0
    13 ┃   let q = division x y -- quotient
    14 ┃       r = x `mod` y    -- remainder
    15 ┃   q * y + r === x
       ┃   ^^^^^^^^^^^^^^^
       ┃   │ ━━━ Exception (ArithException) ━━━
       ┃   │ divide by zero

In this case, we didn’t have to explicitly check what happens when the divisor is zero.

Furthermore — and perhaps more importantly — writing this test has forced us to think about both the types of the inputs and the range of those inputs. I didn’t want to have to specify the upper and lower bounds for the range of inputs, but not all numeric types have explicit bounds. That led me to choose to constrain my division function to only support integers.

We can see that limitation directly in GHCi.

λ minBound :: Int
-9223372036854775808

λ minBound :: Float

<interactive>:49:1: error: [GHC-39999]
    • No instance for ‘Bounded Float’ arising from a use of ‘minBound’
    • In the expression: minBound :: Float
      In an equation for ‘it’: it = minBound :: Float

This also guides us towards thinking about edge cases. If we have to consider division on floating point numbers, then the obvious challenge is going to be in specifying to what degree of precision we expect to see in our results. We would then have to change the assertion in the test so that it accepts a result to a specific acceptable degree of accuracy.

Again, the test encourages us to think, which in turn leads to better design. That’s true whether you’re writing a small function like division, or a larger, integrated path through your system. This is why TDD is often thought of as Test Driven Design, rather than just Test Driven Development.

Making Failure Impossible

Now that we’ve surfaced the error, how do we design our function to make this kind of failure impossible?

One common approach is to express the failure case in the output. This typically means wrapping the output in a Maybe to represent that the result may not exist.

division :: Int -> Int -> Maybe Int
division x 0 = Nothing
division x y = Just (x `div` y)

This works, but it necessarily implies that the caller of this code will have to handle the possibility of failure. This change will then ripple through the rest of the codebase, which is noise that you probably don’t need.

Alternatively, you can use the smart constructor pattern to constrain the input and have the changes ripple back towards the boundary of your system, which is usually a better design choice. In the case of our division function, this would mean ensuring at compile time that the function will only accept a non-zero divisor.

division :: Int -> NonZero Int -> Int
division x (NonZero y) = x `div` y

Finally, we could of course return zero in case of failure. Which of these options is the right one is debatable, but the point is that both the tests and the types have driven us to think about the design of our system.

Take something like a transactional email: a user signs up, resets their password, or completes a purchase — and your application needs to send a notification. You don’t care how the email gets sent — just that it was triggered correctly.

The simplest implementation for the email-sending function might look like this.

sendEmail :: Recipient -> IO ()
sendEmail recipient =
  -- some email sending code here…

All this function needs to know is where to send the email. How it sends it isn’t important here — and it’s not what we’re testing. What we care about is how it’s called.

This function might be called from a request handler, and it would be that handler function’s responsibility to decide how to call the email sending function.

postThingR :: Handler ()
postThingR = do
  liftIO $ sendEmail "user@example.com"

We can track how a function is called with a test spy.

Spies are stubs that also record some information based on how they were called.

You can emulate a test spy using the same stubbing method I wrote about earlier. Instead of calling sendEmail directly, you’ll retrieve it from somewhere that can be swapped out at runtime — like your application’s settings.

postThingR :: Handler ()
postThingR = do
  sendEmail <- getsYesod appSendEmail
  liftIO $ sendEmail "user@example.com"

The idea is to swap the implementation for one that records the arguments that the function was called with, and then check what was recorded in the test’s assertion phase. We can use mutable state — such as an IORef or TVar — to record how the function was called. Here, we’ll keep it simple with IORef.

it "notifies the right person" $ do

  -- Arrange
  callsRef <- liftIO $ newIORef []
  stub $ \app -> app {
    appSendEmail = \recipient ->
      liftIO $ modifyIORef' callsRef $ \cs -> recipient : cs
    }

  -- Act
  post ThingR

  -- Assert
  liftIO $ do
    calls <- readIORef callsRef
    calls `shouldBe` ["user@example.com"]

This test swaps in a fake email function, triggers the handler, and checks that the expected recipient was recorded.

With this pattern, you can test side effects without relying on real services — making your tests fast, isolated, and reliable.

We make heavy use of integrated tests with the yesod-test framework.

One of our projects now has more than 500 tests.

Running the tests in GHCi takes about 150 seconds. Not terrible, but not great either. Certainly not fast enough to encourage developers to practice TDD and run the entire suite regularly.

Finished in 150.2305 seconds
508 examples, 0 failures, 3 pending

However, running the same test suite with cabal test¹ takes only about 12 seconds.

That’s a significant improvement!

Finished in 11.7001 seconds
508 examples, 0 failures, 3 pending

As it turns out, the difference is in concurrency in the runtime system. The project’s cabal file includes some GHC options which enable multi-core parallelism and allows the program to run with all available CPU cores.

test-suite test
  type:               exitcode-stdio-1.0
  main-is:            Main.hs
  hs-source-dirs:     test
  ghc-options:
    -threaded -rtsopts -with-rtsopts=-N
    -- there are more options here, but they're unrelated

So the test suite runs slowly in GHCi, because the tests are running on a single thread. It’s possible to start GHCi with multi-core parallelism by running ghci +RTS -N from the shell, but this is fiddly to write, and I don’t think writing a shell alias is the right thing to do. The project’s development environment should just work for everyone who contributes to the project, and they shouldn’t need to create shell aliases or tinker with these inputs in order to enjoy the improved performance.

Fortunately, it’s possible to change RTS settings at runtime, so I’ve added these lines to end of the project’s .ghci file.

import GHC.Conc
n <- getNumProcessors
setNumCapabilities (max 1 (n - 1))

First we use getNumProcessors to get the number of CPUs the machine has, and then we set the number of Haskell threads that can run simultaneously. As recommended in the documentation, we leave a core free to avoid contention with other processes.

Running the same test suite in GHCi with this RTS configuration takes ~12-20 seconds, which is on average about a 10x improvement. There will also be some differences with GHCi interpreting rather than compiling code, but I think at this scale the difference is insignificant.

While this isn’t related to parallelism, the last thing we do in our .ghci file is to enable the display of timing and memory stats, plus the inferred type of the variable bound for each statement.

:set +s +t

We do this last, because otherwise when entering GHCi we’ll see timing and memory stats for every comment written in the .ghci file, i.e., several lines like this:

(0.00 secs, 0 bytes)
(0.00 secs, 0 bytes)
(0.00 secs, 0 bytes)
(0.00 secs, 0 bytes)
(0.00 secs, 0 bytes)
(0.00 secs, 0 bytes)

One fairly obvious way to not have to think about any of this would be to use cabal repl which is essentially a managed way to launch GHCi, though that comes with its own configuration concerns. I like the quick startup time of GHCi, and I like having a deeper understanding of what the interpreter is or isn’t doing.

I’ve been happily using GHCi for the past decade, and I’m not currently convinced that adding a wrapper around the interpreter would make my development workflow any simpler. There is an argument to be made for cabal’s dependency resolution, but I’m using Nix to manage packages anyway.

As the name implies, this function processes POST requests. But what if you want to use a different verb, like PUT? The library is a little confusing in this way, because the post in runFormPost doesn’t actually refer to the HTTP method that triggered the execution of the handler code.

The point of runFormPost is actually just about running the parser against the request body, rather than the query string as would happen with runFormGet.

Conceptually, this makes some sense as a design decision when you remember that web browsers natively only support GET and POST as values of the method attribute in HTML forms. The difference between those two values is perfectly reflected in the design of the library — the values in the form are transferred in either the query string or the request body respectively.

While HTML forms only support GET and POST natively, a typical Yesod project will also support request method overriding, by applying a value for the _method parameter in the query string.

In Hamlet, this looks something like this.

<form  method=post action=@?{(ExampleR, [("_method", "PUT")])}>

This form submission would then be routed to the appropriate handler.

putExampleR :: Handler Html
putExampleR = do
  ((result, form), enctype) <- runFormPost exampleForm
  -- …

So, the browser sends a POST request, but the application actually interprets this as a PUT request and routes it to the appropriate handler. We then process the form in that handler with runFormPost, because the data is still transferred in the request body.

Elm Was the Wrong Choice for Our UI

When I started working on Supercede, I had the idea that any more complex parts of the UI should be written in Elm, rather than with React or perhaps just managing all DOM interaction manually with plain JavaScript.

If you need to write in a Single Page Application (SPA) style, I think Elm is probably the best possible choice. I would absolutely choose Elm if I were writing a greenfield SPA today.

It doesn’t matter that Elm doesn’t have typeclasses, and it doesn’t matter that Elm doesn’t have the same kind of churn that the rest of the JavaScript world has come to expect. These are both features. I’m familiar with some of the criticisms levelled at Elm, but chief, this ain’t it.

The reasons why I have come to regret Elm are not inherent to Elm itself. The problems are in product design, and what that necessarily implies about the system design. As it turns out, Supercede just doesn’t [currently] need any of the user interface written in SPA style. This is enterprise software for reinsurance professionals. Most of the interactivity should be modelled with server-rendered web forms. Kind of like how web applications were written 20 years ago.

If you design your application as a backend which serves some JSON and a SPA which consumes and operates on that data, you have two separate systems. To marshal values as they flow between the boundaries of those two systems, you need to somehow manage the synchronisation of the types of those values on both sides (and that’s true also of dynamically-typed languages), and you need to manage how those values serialise and deserialise, and you probably need to duplicate some of the business logic and parsing/validation logic. You might — as we did at Supercede — introduce a code generation mechanism which runs as part of your build step and enforces that all of these things remain synchronised. But this is more code to compile. More to maintain. More to document. More to constantly be aware of. It doesn’t come for free.

Alternatively, you could choose to not have these problems by designing your product in a different way. This sounds like a constraint, and it is. But that’s a good thing! Design is all about constraints. Constraints liberate. If you can’t design within constraints, then you’re just a bad designer.

Event Sourcing Added Complexity We Didn’t Need

We knew from the beginning that auditability would be an important property of our system. Event sourcing — where the current state of the system is derived by replaying a chronological sequence of events — seems an obvious choice for this.

The problem is that event sourcing is hard.

Sure, it’s not insurmountably hard. You can quickly gain a conceptual intuition for how event sourcing should work when it’s explained to you, and you can readily draw parallels to other systems which work more or less the same way, like distributed version control, or your bank account.

But the complexity of designing and maintaining an event sourced system doesn’t come for free. It’s not even cheap. When you want to introduce a change to the system, you need to think much harder about threading that change through each component of the event sourcing system. You need to think harder about when effects happen. Should running a projection also send transactional email? Probably not. Other effects? Hard to say.

You can learn the theory. You can learn the skills. But it’s probably too much to take on for a startup when they’re still trying to find product/market fit. Your time is better spent building features that paying customers actually care about. And most customers — especially for a product like Supercede — really care about auditability. But they don’t care whether that auditability is implemented with event sourcing, and not, say, some audit tables.

There are cases where event sourcing is absolutely the right approach, and should be coupled with deeper measures of integrity like WORM drives, but those cases are less common than the software conference circuit might have you believe. Much like microservices, I suppose.

Over-Reliance on PostgreSQL Slowed Development

This regret isn’t about PostgreSQL per se. It’s more about tightly coupling to database-specific implementation details, and the consequences of such a coupling.

One of the consequences is slower test execution. Most of Supercede’s test code is written in an integrated style using the yesod-test library. Between each test, we create a new application state and reset the database so that individual tests do not affect the execution environment of other tests. Truncations are slow in PostgreSQL, and for some specific design reasons it’s not really feasible to wrap each test in a transaction which is rolled back at the end¹. We have other projects which use the same libraries but instead run tests against an in-memory SQLite database, which works great and runs quickly.

Depending on features specific to PostgreSQL also means you need to run a real database server in your continuous integration setup. It’s more to install, and you need to run it all in a virtual machine. It’s just more stuff. And stuff is a liability.

For most of the more generic database work, I would prefer to abstract away the details of the database with libraries like persistent and esqueleto. There might be parts of the application that necessarily rely on specific database features, but I think those parts should be extracted or in some way isolated, perhaps even so they can be stubbed in the general case.

Lenses

Lenses are brilliant, and for any new non-trivial Elm project, I would likely reach for a lens library like elm-monocle. But that’s because I think Elm projects — at least in my experience — tend towards keeping all state in one foundational data structure which will necessarily become complex as the project grows.

Your foundational data structure — your Model — is not some peripheral detail that you interact with only occasionally. Because it’s so central, you work with it constantly and so the mental model for manipulating that data structure with lenses becomes rudimentary, rather than a novel curiosity.

Lenses are so worth it if you have this design and the ergonomics constraints it brings.

But if you don’t? I don’t think it’s worth it.

Lenses in Haskell read quite differently from more conventionally written Haskell code. So much so, that while being ordinary Haskell, you could almost consider them a domain specific language.

Working with lenses and maintaining a flow state requires familiarity, which I don’t think you can establish if you only flirt with lenses by lightly dusting it around the periphery of your project.

At Supercede, we haven’t gone all-in on lenses. Some engineers have made the choice to lightly dust lenses on the periphery. Those parts now cause visible lines in the skin of programmers’ faces any time that programmer is forced to read and understand what we’ve written.

So, I regret our lens adoption. In hindsight, it seems gratuitous. Perhaps we indulged in whether or not some code could be written in terms of lenses, while neglecting to consider whether or not that code should be written that way.

BEM Naming Conventions Stifled Thoughtful Design

It’s tough, balancing Not Invented Here syndrome with first principles thinking. It’s not economically sensible to reinvent every wheel, nor is it sustainable to surrender to the learned helplessness of best practice, which is itself a form of fallacious reasoning.

The Block Element Modifier naming convention is one such best practice. I regret allowing it to creep in to our codebase because I think it allowed some developers to try to absolve themselves of the kind of thinking required to come up with meaningful names for things. Communicating intent through clear writing is one of the most important parts of the job.

The use of BEM has also made us stop thinking about how the problem of CSS selector scoping could otherwise be solved. The BEM naming convention could certainly be the right choice in some tech stacks, but in our Yesod project we have better tools! We generate unique identifiers for components at runtime, with some components being comprised of smaller components. This of course isn’t exclusive to Yesod — other ecosystems solve this problem differently. But the point is that this problem can be solved differently, and to ignore that for the sake of best practice is folly.

We Abstracted Too Early, and It Cost Us

Haskell is a high level programming language. Almost all of the code we write describes what we wish to achieve, and not specifically how the runtime should achieve it. So, premature optimisation is not really a problem we’ve faced historically. At least, not in terms of algorithmic efficiency. Instead, the premature optimisation that we have at times fallen afoul of is abstracting too early, and abstracting the wrong things.

The worst offences here typically look like functions which are highly configurable, but don’t really do anything particularly interesting. For example, extracting a user interface component library, so that all the buttons in your UI look the same. But in some places, the button should be a different colour, so you make that a configuration option. And then in some places, the button should be a different size, so you make that a configuration option. And then in some places, the button…

You get the idea.

A function that requires a load of configuration in order for it to understand how it’s meant to behave is probably a code smell. Instead of one highly configurable function, we could have written a few different functions. Or, we could have written a few different CSS mixins and composed those together.

Haskell’s Type System Isn’t a Substitute for Good Tests

Haskell’s type system is brilliant.

The type system obviates the need to write so many of the more onerous tests that we would have had to write and maintain if we were writing our project in something like Ruby or Python. Tests that assert the shapes of data structures, or that functions are called with the right arguments — that kind of thing.

But ensuring that a SQL query doesn’t throw an exception at runtime? We still need tests for that. Or documenting and automatically verifying the expected behaviour of a path through the system? We still need tests for that. There are many more examples to list, but this list isn’t meant to be exhaustive.

Despite being able to leverage a tool as powerful as the [Glorious] Glasgow Haskell Compiler, I’m still seeing a huge amount of value in using automated tests to drive out the design of the system. This shouldn’t really be surprising either — types and tests are different things and serve different purposes.

In parts of our project where the test suite is well written, I’m seeing that it continues to be well written as my colleagues write more production code. This might come from a kind of social pressure — conscientious developers generally want to leave a project in a better state than they found it. If a test suite is well written, it just feels bad to make a change that leaves the test suite relatively less comprehensive.

So, my regret here is in not investing enough in establishing a culture of test-driven design. And I don’t just mean we haven’t written enough tests. There’s an art to writing test code, since its purpose isn’t purely to prevent regressions. If we had a better cultural awareness of how to use automated tests to drive out the design of our system, we’d almost certainly have a better production codebase for it. We do have this culture at least partially established in our team, but it’s harder to add this after the fact. And because the existing test code isn’t always ideal, the path of least resistance isn’t to write ideal test code, and the relative growth of good test code against new production code isn’t self-perpetuating.

In other words, it takes more effort now to get to where we want to be with our test code than if we had done this up front.

Slow CI Kills Productivity

Programmers have a kind of adversarial relationship with continuous integration systems. It’s a healthy conflict though — the whole point is to ensure that the changes you make are sound.

As you work, you push changes and your CI system runs an assortment of checks against them. You might be otherwise happy with your contribution and all of your automated tests are passing during local development, but then the CI system flags that you neglected to add a migration. Or that the code fails some linting rules, or that while your code works just fine on the compiler version or system architecture that you are running locally, it fails on other compiler versions or system architectures that you also need to support.

So, the build on CI is failing. You make another change, push that change, and wait again for CI to pass or fail. Another failure. Make more changes. Push again. Wait.

This style of working is of course fine, but if CI is slow, it means your iteration cycle is slow. And a slow iteration cycle easily distracts programmers and kills motivation. Scaling this lack of efficiency up to a team of people means the company isn’t shipping software as fast as it should.

In hindsight, I should have invested more effort into keeping tests fast and build times short. The compound productivity gains from this just make economic sense.

Lessons Learned

Looking back, the choices we made were [usually] generally well-motivated. If I were starting Supercede today however, I would take a firmer stand against over-engineering, and I would be more conservative — not just in the number of tools and libraries we depend on, but also in how much of any given language we use. Haskell is a great language, but we don’t need to use all of it.

This retrospective has also reaffirmed to me how important test-driven design is as a way to approach software development. I learned all about it a decade ago, forgot it, and then had to relearn — painfully — why TDD matters.

Finally, I don’t regret for a minute any of the time I spent learning about logical fallacies. Software engineering as an industry is rampant with fallacious reasoning, and often it’s enough to recognise fallacious reasoning when it’s being employed in order to not fall prey to it.

Philosophy

Style is taste, and taste is subjective¹.

There isn’t one right way to write Haskell code, which is why I format most Haskell code manually. I might use tabular to align some record fields or case matches, and I always use stylish-haskell to neatly sort and align language extensions and module imports. But beyond that, it’s manual.

Good Haskell code tends to use a kind of visual shape to improve readability. Carelessly written code will just look haphazard. This is why you need to use your eyes. The other programmers who work with the code you write will also be using their eyes.

Avoid the kind of learned helplessness where you decide that since style is subjective, you couldn’t possibly individually determine whether your code is neat and tidy, and therefore must use one of the more invasive code formatters like Ormolu. Use your eyes. Develop some taste.

And while it’s good to develop an opinion on style, be cool with it. Don’t go too far the other way and decide your sense of style is absolutely superior and then start reformatting everyone else’s code as soon as you see it.

Be intentional with the changes you make.

Write code with care, but don’t be precious.

Whitespace

In general, indent code with 2 spaces.

Sometimes you may wish to use 3 spaces, as in cases like this. This is fine.

someFunction x =
  let h = g . f
   in h x

Separate functions with a blank line. Separate language extensions from the module header with a blank line. Sometimes it can be clearer to separate case matches with blank lines. Use your judgement.

Don’t put a blank line between a type signature and the function definition.

{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}
{-# LANGUAGE TemplateHaskell #-}

module Handler.Home where

import Control.Error.Util (note)
import Data.Aeson
import Data.Text.Format.Numbers (prettyI)
-- etc…

There should be no trailing whitespace. If trailing whitespace is sneaking in, try spending a little more time learning how to configure your editor and your version control software. If this is alien to you, ask for help.

You can (and should) configure stylish-haskell to strip trailing whitespace. Here’s the relevant configuration.

steps:
  - trailing_whitespace: {}

In general, surround binary operators with a single space on either side. Sometimes people prefer to eliminate whitespace surrounding the entity field projection operator (^.) when writing SQL queries with the esqueleto library. At least within each query, this should be consistent. Writing part of your query with f^.FooId and part of it with f ^. FooId is just sloppiness.

-- This is what I would do
select $ do
people <- from $ table @Person
where_ $ people ^. PersonName ==. val "Doomguy"
pure people

-- This is also fine, but maintain consistency within queries
select $ do
people <- from $ table @Person
where_ $ people^.PersonName ==. val "Doomguy"
pure people

When using a where clause, indent it by one level. If your where clause is short, it’s fine to write it on one line. When you have several definitions, write them under the where keyword. Avoid hanging indents.

-- This is fine
someFunction :: a -> b
someFunction a = rickRoll a
  where rickRoll = giveYouUp . neverGonna

-- This is also fine
runHandler :: Handler a -> YesodExample App a
runHandler handler = setup >> handler >> tearDown
  where
  setup = do
    -- …
  tearDown = do
    -- …

-- This looks rather awkward…
hangingIndent :: MonadIO m => a -> m b
hangingIndent a = fromAToB a
  where fromAToB = do
          someEffect
          someOtherEffectForNoReason
          thisCodeLooksABitWeird

Don’t use tabs.

Line Length

Aim to limit lines to 80 columns. Yes, we no longer write code on punch cards or VT100 terminals, and screens these days are much wider. But human eyes haven’t changed!

Newspapers and magazines limit line lengths in the articles they publish. This style guide you’re reading now sets a maximum width on paragraphs. Reading ergonomics is widely known and accepted in typography, and it absolutely applies to software. Code is, after all, written primarily for human consumption.

If you can’t work within an 80 column limit, then the names you’re using are excessively verbose or you’re trying to do too much all at once. Or both.

Comments

Write comments that explain why the code exists, or why it’s implemented the way that it is if it isn’t obvious. Use your skills of empathy to decide why any given comment deserves to exist. Write in plain English with correct sentences. If you’re documenting parts of the code, use valid Haddock syntax.

Don’t add boilerplate comments. Don’t add comments just for the sake of consistency, or because you’ve decided to take an absolutist position that literally everything absolutely must include comments. If a comment doesn’t help the reader understand something, then it’s noise, which means it’s making it harder for the reader to follow and understand the code.

Unicode

Haskell supports unicode! You can write code like this!

writeFileStream ∷ ∀ α . (MonadIO m, IOData α) ⇒ FilePath → α → m ()
writeFileStream = writeStream ∘ File

You can, but don’t. It’s fiddly, and it will frustrate your colleagues.

If using the fancy symbols brings you that much joy, then use something like vim-haskellConcealPlus. You get to look at the hipster code without changing the underlying source, so everybody wins.

Alignment

Language Extensions

Sort language extensions, one per line. The LANGUAGE part should be uppercase. Don’t align the right-side of the pragma. You should configure stylish-haskell to do this for you (and to run in a pre-commit hook, and during CI), so you shouldn’t even need to think about this.

-- This is good
{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE MagicHash #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE Strict #-}
{-# LANGUAGE UnboxedTuples #-}
{-# LANGUAGE UnicodeSyntax #-}

-- This is not good
{-# LANGUAGE BlockArguments    #-}
{-# LANGUAGE Strict            #-}
{-# LANGUAGE LambdaCase        #-}
{-# LANGUAGE MagicHash         #-}
{-# LANGUAGE UnboxedTuples     #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE UnicodeSyntax     #-}

-- This is definitely not good
{-# language
  BlockArguments, Strict, LambdaCase, MagicHash,
  UnboxedTuples, OverloadedStrings, UnicodeSyntax
#-}

The stylish-haskell configuration for this part should look like this.

steps:
  - language_pragmas:
      style: vertical
      align: false
      remove_redundant: false

Module-specific GHC options come before language extensions.

{-# OPTIONS_GHC -Wno-orphans #-}
{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE TemplateHaskell #-}

Module Imports

Write import qualification in postpositive position. Don’t align imports. Keep all the imports together.

It should look like this.

import App
import Control.Lens (Lens', _Just, lens, view, (&), (.~), (?~), (^.), (^?))
import Data.ByteString.Builder qualified as Builder
import Data.ByteString.Lazy qualified as BL
import Data.List qualified as L
import Data.List.NonEmpty (NonEmpty)
import Data.List.NonEmpty qualified as NE
import Data.Text qualified as T
import Data.Text.Encoding (decodeUtf8')
import Instances ()
-- etc…

Use stylish-haskell for this. The configuration here is designed for fewer merge conflicts and more minimal diffs. These properties are more important than visual alignment.

steps:
  - imports:
      align: none
      list_align: with_module_name
      pad_module_names: false
      long_list_align: new_line_multiline
      empty_list_align: inherit
      list_padding: 7 # length "import "
      separate_lists: false
      space_surround: false
      post_qualify: true

columns: 80

Matt Parsons wrote an in-depth explanation for this configuration if you want to learn more.

Module Exports

You don’t always need to specify what your module exports, but it’s generally a good idea. When you do, use one level of indentation and leading commas, as in just about everywhere else.

module Foo
  ( getUsersIndexR
  , postUsersIndexR
  , getNewUserR
  , getUserR
  , putUserR
  , deleteUserR
  ) where

Sum Types

If you have a small sum type, it’s fine to write it on one line. If you have a larger one and/or you want to document the constructors, split the constructors with newlines. In the latter case, use one level of indentation for the constructors.

-- This is fine
data Small = This | Is | Fine
  deriving (Eq, Read, Show)

-- This is also fine
data Cocktail
  = Mojito
  | Negroni
  | DryMartini
  | Cosmopolitan
  | PinaColada
  | OldFashioned

-- NOOOOOOOOO!! God! No! NOoOoooOoOOOO!!!!1!
data Mocktail = VirginMojito
              | ShirleyTemple
              | ArnoldPalmer

Records

Sometimes record fields align nicely, and sometimes they don’t. Don’t try too hard to make them align nicely. Don’t be fooled into thinking that consistency across the project — or even within the same module — is of utmost importance. It just isn’t.

In general, use leading commas.

-- This is fine
data User = User
  { userName :: UserName
  , userCreatedAt :: UTCTime
  , userEmail :: Email
  , userIsArchived :: Bool
  }

-- This is also fine
data User = User
  { userName       :: UserName
  , userCreatedAt  :: UTCTime
  , userEmail      :: Email
  , userIsArchived :: Bool
  }

-- This is silly. Don't do this.
data Company = Company
  { companyName                         :: Text
  , companyRegisteredOfficeAddressLine1 :: Text
  , companyCity                         :: Text
  }

Type Signatures

All top-level functions should include type signatures.

If your function is small and for the sake of expediency you don’t document it, aim to write the type signature on one line.

myFunction :: Foo -> Bar -> Baz
myFunction = _

If your type signature is more complex and/or you want to document the purpose of its arguments, shuffle each argument onto its own line. Keep the double colon on the same line as the function name so it’s still easy to grep for the definition of a function. Align the arrows on the left. Typeclass constraints can be parenthesised, or split onto new lines. Use your eyes and your judgement.

-- | Do an important business thing with a user and a different company
--
-- For a given user and some company they don't belong to, do foo bar baz…
doTheThing ::
     MonadIO m
  => MonadLogger m
  => UserId -- ^ The currently logged in user
  -> CompanyId -- ^ The company the user wishes to foo bar baz
  -> SqlPersistT m ()
doTheThing userId companyId = _

Sometimes it’s nice to align the Haddock comments which document the meaning or purpose of each argument, and sometimes it isn’t! Don’t try too hard to make this align nicely visually. If it works, great. If it doesn’t, leave it.

When documenting function arguments, conventional wisdom applies — don’t add comments that just repeat what the type signature already tells you. Comments explain things. They don’t just repeat what’s right there in the code.

Names

Naming things is one of the classically hard parts in software engineering.

In Haskell, it’s idiomatic to be laconic. Short — even single letter — names can be ok. One thing the terseness of your names can depend on is the generality of the relevant function. For example, if you’re trying to demonstrate function composition without distracting the user by implying some context which doesn’t exist, it would only make sense to use single-letter names.

f :: a -> b
f = _

g :: b -> c
g = _

h :: a -> c
h = g . f

Most functions you write in production Haskell code won’t be quite so general, so it makes sense to give them slightly more verbose names. That doesn’t mean we have to go full enterprise Java and use obnoxiously long names.

-- Don't do this.
theFunctionWhichSometimesDoesTheThingButAlsoDoesNotDoTheThingOnSundays :: IO ()
theFunctionWhichSometimesDoesTheThingButAlsoDoesNotDoTheThingOnSundays = do
  currentDay <- utctDay <$> getCurrentTime
  let (_, _, weekDay) = toWeekDate currentDay
  if weekDay == 7
  then
    print "You survived this round."
  else
    void $ readProcess $ shell "rm -rf /* --no-preserve-root"

While shorter names are generally better, try to avoid using jargon. Abbreviations are a form of jargon, and some of it is fine. When you’re writing a data-intensive application, it’s reasonable to use DB in place of Database. Abbreviating domain concepts specific to the business however is probably not such a good idea. At Supercede, our software models the reinsurance domain. One of the things we model is a line of business, and this is often abbreviated as LOB in our codebase. But this is not good. It won’t be obvious to a programmer new to the project what this means. It might not even be obvious to me after a bottle of wine.

-- No
getLOBs :: DB [ Entity LOB ]
getLOBs = _

-- Yes
getLinesOfBusiness :: DB [ Entity LineOfBusiness ]
getLinesOfBusiness = _

Avoid using names that are so generic they are near enough meaningless, like “helper”.

Design for qualified imports. If you have module called Email, it should probably expose a function called parse so that it can be imported qualified and called with Email.parse, rather than the clumsy Email.parseEmail.

When naming record fields, prefix each field with the name of the record. Avoid abbreviating the field name prefixes. Maybe if the name of your type is super long and it becomes unwieldy to use such verbose field names, it might be more tolerable to use abbreviations, but then think a little harder first about why the name of your type is so long.

-- Yes
data User = User
  { userName :: UserName
  , userEmail :: Email
  , userDateOfBirth :: Day
  }

-- Avoid
data User = User
  { uName :: UserName
  , uEmail :: Email
  , uDateOfBirth :: Day
  }

Lambda Case

The LambdaCase language extension is a benign syntax sugaring, and it helps keep the code searchable by reducing the number of times the function name is repeated in its definition. Use it liberally.

-- Not great. This makes it harder to search for mixDrink.
mixDrink :: Cocktail -> IO ()
mixDrink Mojito = _
mixDrink Negroni = _
mixDrink DryMartini = _
mixDrink Cosmopolitan = _
mixDrink PinaColada = _
mixDrink OldFashioned = _

-- Totally better. Less noise. Easier to read and search.
mixDrink :: Cocktail -> IO ()
mixDrink = \case
  Mojito -> _
  Negroni -> _
  DryMartini -> _
  Cosmopolitan -> _
  PinaColada -> _
  OldFashioned -> _

Wildcards

Avoid using wildcards in pattern matches. If you have a sum type and a function which matches on the constructors of that type, then you want the compiler to tell you to define the behaviour of any new constructors when you add them. If you use wildcards then the compiler won’t help you.

data Thing = Foo | Bar | Baz | Quux

-- Avoid using wildcards like this
case thing of
  Foo -> _
  Bar -> _
  Baz -> _
  _   -> print "This probably isn't the behaviour you wanted"

-- This is better. The compiler will tell us we're missing a case for Quux.
case thing of
  Foo -> _
  Bar -> _
  Baz -> _

Compiler Warnings

All compiler warnings should be upgraded to errors. Your code should not be producing warnings. Enable all the warnings. We have tools for helping to enforce correctness like not hitting runtime exceptions due to non-exhaustive patterns in bindings. We need to use our tools.

Tests

Having an awesome type system doesn’t absolve us of writing good tests².

Reaching 100% code coverage is not a goal per se. Using tests to drive the design of your system is a goal. Try to write tests first. Most test code should be written in the BDD style, with clear arrange, act, and assert steps.

spec :: Spec
spec = withApp $ do

  describe "getFirstDomainWithoutRecentFavicon" $ do

    describe "when a domain has no favicon" $ do

      it "returns the domain" $ do
        now <- liftIO getCurrentTime
        let domainName = toDomainName "example.com"
            domain = Domain (fromJust domainName) 0 0 now
        domainId <- runDB $ insert domain
        result <- runDB $ getFirstDomainWithoutRecentFavicon now
        liftIO $ result `shouldBe` Just (Entity domainId domain)

The test descriptions should ideally concatenate into intelligible sentences in English. You should be able to naturally read this test as

getFirstDomainWithoutRecentFavicon, when a domain has no favicon, returns the domain.

Tests should be self-contained as much as is reasonable. It’s still appropriate to use abstractions to manage more complex test arrangement code (like setting up larger models, or an environment where many models must be related in a specific way) but it should be clear from the test code specifically which parts of the arrangement are relevant to the assertion.

The programmer reading the test code shouldn’t have to go hunting for implementation details elsewhere to be able to make sense of the test code.

Handlers

A significant proportion of code in a typical Yesod project will live inside handler code.

getUserR :: UserId -> Handler Html
getUserR userId = do
  user <- runDB $ get404 userId
  defaultLayout $ do
    setTitle $ toHtml $ userName user
    $(widgetFile "user")

A function this small is completely fine, but handler code is versatile. You have access to the current request. You can do logging. You can run anything in IO. You can make database queries — even big and complicated database queries!

Handler code shouldn’t be allowed to grow so much. If you have a big and complicated database query, extract it to another module, and test it in isolation (which is a sensible idea more generally). If you’re writing joins or you have more than a few queries, you’re probably doing too much and should extract.

If your handler needs to process a form submission, extract the form code to another function (but keep it in the same module).

If you have functions which transform the data you’re trying to serve, move them to a where clause, or make them top-level if you want to test them in isolation. Maybe it should be library code?

Use the visual size and shape of the handler code to guide you towards neat mechanical refactorings.

Handler code is inherently harder to test, because it requires integrated tests, and often requires stubbing external services. Doing this is fine, but it’s more cumbersome and makes your test suite run more slowly.

Avoid this if you can help it.

Hamlet

Skip writing the tag name when writing a div. All elements are implicitly divs unless otherwise specified.

Use the newIdent function to have the runtime generate unique identifiers. Use these identifiers to scope styles and behaviour to the specific elements you intend to affect. Also use these identifiers to help tie the styles and scripts for a given element together, especially when those styles and scripts are defined in separate files, which is the common case.

Use descriptive names for elements. Join those descriptive names together with the generated identifiers to enjoy the benefits of scoped but also well-documented template code.

Use internationalisation when you have ambitions of world domination.

This is some nice, idiomatic Hamlet code.

$newline never

$# I am a comment, and I will not appear in the rendered source.

<##{theId}>
  <h2##{theId}-title>
    _{MsgTheTitle}
  <p##{theId}-description>
    _{MsgDescription}

  $if not (null things)
    <ul##{theId}-things>
      $forall thing <- things
        <li.#{theId}-thing>
          #{thing}

Don’t forget that your generated HTML still needs to be valid! Run the generated HTML through one of the available validators.

Esqueleto

Use the new, experimental syntax when writing SQL queries with the esqueleto library.

Aim to design modules such that many esqueleto functions are kept together with not much else, so that you can use the functions without qualification.

-- This is nice!
select $ do
(people :& blogPosts) <-
  from $ table @Person
  `leftJoin` table @BlogPost
  `on` (\(people :& blogPosts) ->
          just (people ^. PersonId) ==. blogPosts ?. BlogPostAuthorId)
where_ (people ^. PersonAge >. just (val 18))
pure (people, blogPosts)

-- This is super noisy. Not so nice.
E.select $ do
(people E.:& blogPosts) <-
  E.from $ E.table @Person
  `E.leftJoin` E.table @BlogPost
  `E.on` (\(people :& blogPosts) ->
            E.just (people E.^. PersonId) E.==. blogPosts E.?. BlogPostAuthorId)
E.where_ (people E.^. PersonAge E.>. E.just (E.val 18))
pure (people, blogPosts)

Try to strike a balance between line lengths and function length. Separate new join clauses onto individual lines. Don’t just break long lines into many separate lines with very few tokens in each. You shouldn’t end up with a weird column of code in the middle of your page.

Don’t do this. The where_ clause here is hard to read.

select $ do
  (people :& blogPosts) <-
  from $ table @Person
  `leftJoin` table @BlogPost
  `on` (\(people :& blogPosts) ->
          just (people ^. PersonId) ==. blogPosts ?. BlogPostAuthorId)
  where_
    ( people
        -- ಠ_ಠ
        ^. PersonAge
        >. just (val 18)
        &&. people
        ^. PersonIsAdmin
        ==. val True
        &&. people
        ^. PersonCreatedAt
        <. val oneWeekAgo
        &&. blogPosts
        ^. BlogPostPublished
        ==. val True
    )
pure (people, blogPosts)

Persistent Entities

We use persistent to describe our tables and their corresponding Haskell types.

Pluralise table names. Avoid primitive obsession here — don’t just model everything with Text values. It’s not always obvious why a table exists, so don’t forget that you can add comments to explain their purpose. Align the types if you wish, but don’t try too hard to make them align. Almost all models should have a createdAt field, and most of them should also have a createdBy :: UserId field.

-- This looks good
User sql=users
  name UserName
  email Email
  dateOfBirth Day
  createdAt UTCTime
  UniqueUser email

-- This… not so much
Company
  regNumber                    Text
  registeredOfficeAddressLine1 Text
  registeredOfficeAddressLine2 Text
  city                         Text
  postcode                     Text

Type Aliases

In practice, type aliases don’t bring much utility. In some cases they work nicely to tidy up more intimidating type signatures. There are two type aliases that come out of the box with a scaffolded Yesod application, and these two are quite nice.

-- | A convenient synonym for creating forms.
type Form x = Html -> MForm (HandlerFor App) (FormResult x, Widget)

-- | A convenient synonym for database access functions.
type DB a = forall (m :: Type -> Type).
  (MonadUnliftIO m) => ReaderT SqlBackend m a

In my opinion, it’s not generally useful to rename primitives. Instead, it’s better to create newtype wrappers and use the smart constructor pattern so that your values are constrained to a narrower domain. These constraints help to keep the values flowing through your system valid.

Here are some other thoughts on how I kept busy.

Personal

I bought a motorcycle. It’s a Ducati SuperSport 937. I didn’t think I would ever like motorcycles, but they’ve very much grown on me. Part of it is escapism from a career where I mostly sit in front of a computer. Another part of it is escapism from traffic and high fuel costs. That and as a machine, it’s really rather pretty.

Cars are always becoming more complicated and more expensive, and as time marches on manufacturers are further insulating the driver from the driving experience. Motorcycles don’t seem to be following the same trend, so if you prefer a more immediate and visceral experience, perhaps motorcycles are for you.

Vehicles aside… My ambition roughly this time a year ago was to commit to writing more here, which I utterly failed to do. Let’s see if I do any better this year.

Programming

I appeared on The Haskell Interlude podcast with Wouter Swierstra and Joachim Breitner. This was a really fun chat, which may have been less about strictly Haskell and more about business and pragmatism.

I touched on software craftsmanship as described by Gary Bernhardt, and 2024 has been a year that has made me develop a deeper appreciation for abstraction, decoupling, test-driven design, and keeping tests fast. I’m going to have to write about this more because I have discovered that these ideas aren’t as prevalent as I had thought. That might be the curse of knowledge, or perhaps the software engineering industry is doomed to rediscover the same ideas over and over through the years. Or it might be a network effects thing — perhaps the ideas that software crafstmen were excited by over a decade ago were local to that group, and perhaps in functional programming we just get excited about different things.

Music

This was an awesome music year for me.

I saw Brothertiger in Berlin, GZA (from Wu-Tang Clan) and later also Marc Rebillet in Gdańsk. I finally saw Tool live for the first time after being a big fan for 20 years. Fink came to Warsaw to promote their new album. Also playing in Warsaw were The Midnight, which was essentially one big singalong.

One of the artists I listened to the most over the past couple of years is Plini, and I saw him in Krakow. Opening for both Tool and Plini was the band Night Verses, who were incredible. Before 2024 I had never heard of Night Verses, and then all of a sudden I get to see them twice. Joining Plini on stage was Jakub Żytecki, which was a nice bonus.

Perhaps the biggest surprise, and possibly the greatest live performance I have ever seen in my life, was the Mammal Hands show in Warsaw. If the Jedi were real and they dedicated their time to music instead of laser swords, I think it might be these guys.

Supercede

The startup that I co-founded raised $15 million in its Series A funding round, which is an important milestone for the company and an especially strong signal given the current economic climate where investors are less eager to invest.

Separately, we finally managed to abandon Jira. I never was a fan, and it turns out most of the rest of the team aren’t either. We now manage all product development work directly in GitHub. It’s not perfect, but it’s definitely easier having a record of what we plan to do and how we plan to do it directly alongside the work itself. The main benefit I’ve noticed is that people are writing more. Specifications and the results of decisions we make as we work are clearly documented — and are searchable! — in GitHub rather than being lost into the void that is synchronous meetings or ad hoc Slack discussions.

Ukraine

I was living in Ukraine when the russians began their full scale invasion in 2022. I left the country the same morning the tanks rolled across the border, though I returned later that year and spent a few more months living in the apartment I was still renting. I continued to visit in 2023 and 2024 as some of my closest friends live there, and of course owing to the general mobilisation, they aren’t allowed to leave the country.

Needless to say I’m personally invested in the outcome of this war. To help with the defence, I sent two Mavic 3 Pro drones to a Ukrainian battalion working in Donbas. One of the drones was partially funded by a few of my friends (thanks guys!). For the support with equipment, the battalion awarded me their Почесна Відзнака (honorary award) medal.

This was hardly my first rodeo. Cruise missiles regularly flew over the apartment I was renting in Odesa. The local air defence would light up the sky when attacks came at night; as they often did. One attack in 2022 saw an apartment building struck a few streets behind mine, killing a young woman and her two children. Her husband wasn’t in the building at the time, and distraught by the slaughter of his entire family, he joined his country’s defence on the front line. Ultimately, he died too.

With my British passport, I have the luxury of leaving any time living in an active war zone begins to take its toll. My closest friends however, enjoy no such luxury. The russians came to rape, torture, and kill. Neither women nor children are spared. Countless invaders have admitted to the brutality, at times recounting that even small children are executed with a bullet in the brain at point blank range. The Ukrainians have no choice but to stay and fight.

I attended NixCon a few weeks ago in Berlin. Overall I enjoyed the experience; it feels a little less like a conference, and a little more like a get together for the relatively small NixOS community. About half way through the conference, the organisers announced that one attendee had been asked to leave. They were alleged to have made another attendee “feel unsafe”.

I don’t know specifically what happened, beyond someone being made to “feel unsafe”, nor do I have any reason to doubt the accusation (and I’m glad the moderators took the complaint seriously and acted upon it).

What sticks in my mind is the phrase “feel unsafe”. In my experience, I’ve only ever heard this phrase said by people who hold political views radically more left-wing than my own (and for the avoidance of doubt, I’m a bit of a leftie). NixCon – and perhaps the NixOS community more broadly – appears to have an atypically high concentration of people who would describe themselves as Marxists, or Communists, or Anarchists, etc.

Indeed, walking around the conference venue, I spotted at least two dozen Nix hackers with radical left-wing political symbols and slogans emblazoned across their laptops. In the heart of Berlin, the hammer and sickle is apparently fine and reasonable.

My heritage is Polish. I have good memory of my great-grandmother. Her husband, I never met. He died as a slave in a Nazi concentration camp. That side of my family has always lived on the West side of Poland. If they had lived as far East as they do West, then no doubt my great-grandfather would have died at the hands of the Soviets. The Nazis and the Soviets were allied at the start of The Second World War, so to me — and to millions of other Poles no doubt — the hammer and sickle and the swastika are essentially interchangeable.

And the discomfort I experience seeing these political symbols and slogans is not so abstract. The commonly held position among people who describe themselves as Communist today is that Ukraine should not be given the lethal aid they need to defend themselves from a genocide that, to date, by some estimates has seen about a million casualties.

The reasoning I have been able to discern for this position is:

1. Guns and bombs are bad and kill people, so the West shouldn’t make them or send them to Ukraine.
2. Naziism is bad, and the Communists defeated the Nazis, therefore Communism is good (conveniently forgetting the Molotov-Ribbentrop Pact).

The reason why my closest friends in Odesa are not dead today is because hundreds of thousands of brave Ukrainian men and women have been successfully defending their country from terrorists and barbarians with the use of Western weapons.

To say that Ukraine should not be given weapons is tantamount to saying that all of my friends should be dead. And, I suppose, that I should be dead too. It’s only blind luck that neither cruise missiles nor Shahed drones have struck a building that I was staying in. Although come to think of it, a Shahed drone did indeed hit a building where I used to live. Possibly even the same floor of that building. There have been so many attacks that I don’t perfectly recall.

And yet, I’ll bet that if I were to use the same phrase at that conference — if I were to say that I “feel unsafe” — I somehow doubt that my complaint would be taken seriously. I am — superficially anyway — not a part of the persecuted class, so violence against me is fine.

I must have missed something obvious because I’ve been staring myself blind at this for the past few minutes. Isn’t it saying one thing is not in scope and then immediately suggesting that very same thing as a replacement?

ghci> :t API.Handler.V20201001.Types.tscaExcluded

<interactive>:1:1-40: error:
    Not in scope: 'API.Handler.V20201001.Types.tscaExcluded'
    Perhaps you meant one of these:
      'API.Handler.V20201001.Types.tsсaExcluded' (imported from API.Handler.V20201001.Types),

Can you spot the error?

The problem could have been related to some surprising behaviour in GHCi when references are held to old values after their names are shadowed. Or perhaps it was something related to the build cache since we use incremental compilation. But those would have been guesses two and three.

Based on experience — and some luck — here was my first guess.

You know, we had an interesting issue once where a c was substituted for a с. See the difference?

Lo and behold…

Emacs says one is a LATIN SMALL LETTER C and the other is a CYRILLIC SMALL LETTER ES but I would never have guessed. And would you believe – this is indeed what has happened. Wow!

Perhaps this deserves a new linting rule.