Code Health: Make Interfaces Hard to Misuse (2018) | Hacker News Reader

Code Health: Make Interfaces Hard to Misuse (2018)

testing.googleblog.com

62 pointsFiveplus21 comments

For bonus points, you can use a sufficiently strong type system to make your interface hard to misuse in a slightly different direction.

If you require function `setUp : unit -> unit` to have been called before function `doThing : unit -> unit`, you can instead alter the types, introducing a `type Token = private | Token` which the consumer can't create for themselves but which your implementation can create. Then just tweak the types so you have `setUp : unit -> Token` and `doThing : Token -> unit`; since the user can't make a `Token` themselves, they can only have obtained it from calling `setUp` first.

The easiest way to use types for this is to have separate types for (un)initialised values, e.g. instead of having a 'Database' with methods for 'connect', 'select', 'insert', etc. where the caller has to run 'connect' first, we instead split it into two so that the first object (e.g. 'DisconnectedDatabase') doesn't have any query methods, but does have the 'connect' method which returns a 'Database', and the query methods exist on that.

A few things to keep in mind when doing this:

- If we end up with a classes which only has a single method (e.g. 'DisconnectedDatabase' with only a 'connect' method), then it might be better as a standalone function, or a smart constructor, etc. ( http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom... )

- We can use this approach to prevent code being called prematurely (e.g. querying has to come after connecting), but we can't prevent code being called too late; e.g. trying to query after a 'Database::disconnect' method has been called. (This is where linear/uniqueness types, etc. can be used)

>we can't prevent code being called too late

You can get pretty close in C++. All it takes is for the disconnect method to be rvalue-qualified:

void disconnect() &&;

and to turn on use-after-move compiler warnings. Now disconnecting has to be invoked as:

std::move(db).disconnect();

and if you refer to db after that Clang will tell you to knock it off. (Of course, for a database object, it probably makes more sense to use RAII and disconnect in the destructor, but this pattern can help if you have multiple ways for the object's useful lifetime to end.)

That won't catch users who have a pointer or reference alias to the object, but that's more like a use-after-free risk, which exists any time you have references.

I know about this technique and I can pretty much never bring myself to actually do this in practice. For one thing there's pretty much always something more useful to return, and suddenly it becomes incredibly unergonomic to return an extra token and then force the user to pass it elsewhere. For another, it doesn't even automatically prevent passing the token to the wrong instance of the object either, or passing it twice, or other kinds of undesired usage. Adding dynamic checking for any of this also adds runtime overhead, and all this seems quite confusing and difficult to justify, especially for those unfamiliar. (On top of additional issues I'm probably forgetting.) Do you actually find a way to put this technique into good use in practice?

I suppose it's less useful as a standalone technique - I've used it before but not that heavily (e.g. in a library built around sequencing effects in a certain way, where I've wanted to guarantee that one effect can't be called before another). Really we'd want a considerably more powerful type system - Idris 2's quantitative types and/or Rust's ownership, for example - before that particular technique really starts to shine.

However, the general mindset is one I use all the time. For example, if I've written a state machine that is represented explicitly in the types, I might be able to encode some of the state transitions in the type system directly, so the compiler prevents me writing certain invalid transitions. For example, if state B can only be reached after state A, I might write the in-memory representation of B to contain an in-memory representation of A; this guarantees I must have passed something through state A to get anything in state B. Doesn't save you from everything - in particular it doesn't solve your "passing the token to the wrong instance of the object" problem - but any constraint on the state space is useful in my book. When the state machine gets sufficiently large, in my experience, the benefits of the restricted state space start outweighing the negatives of manual token shuffling.

(I have a blog post brewing about this general class of techniques, but I don't know when it'll be ready.)

Couldn't you return a tuple with the object and the useful return value though?

Sure - that's not the difficult part, in my book. (I use F#, where there's tuple destructuring syntax, so it's easy.) The hard parts are about making sure you can't reuse the token in the wrong context.

Oooh. Yeah, that makes sense.

I sadly don't know enough F# to even begin to think of something to make the tokens context safe.

For what it's worth, I don't think it's possible in F# (perhaps modulo absurd tricks that will never go into prod code, like type-level naturals).

With explicit enforced lifetimes it's harder to misuse. The first method returns the tuple of (Something, Token) and the second method consumes/takes ownership of the Token plus whatever its arguments. This way each call to function2 has to be preceded by a call to function1 and it's checked by the compiler.

It's reasonably easier when a method can transparently change the type, for example in Common Lisp - where the object system provides a clear controlled way to change the class of an object (using apropriately called method change-class)

Even better: make setUp return doThing.

Yes and no - `doThing` itself is less inspectable, and it's sometimes helpful to separate the implementation from the instructions. (I wrote https://www.gresearch.co.uk/article/defunctionalisation/ ; the usual introduction is https://blog.sigplan.org/2019/12/30/defunctionalization-ever... .)

Oooh, I did think of that article!

Isn't this basically the point of the builder pattern?

I don't think so? I'm not very well up on my OOP patterns, but in my mind the builder pattern in OOP corresponds to the initial algebra pattern in FP, and initial algebras can model domains with or without that kind of restriction. I think they're basically orthogonal.

Rusty's API scale captures this approach really well:

How Do I Make This Hard to Misuse? https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html

What If I Don't Actually Like My Users? https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html

Avoiding temporal coupling is always a win.

Bonus points for avoiding mutable state in classes entirely. It’s certainly not always possible, and requires a shift in mindset, but we’ve been trying to actively avoid state not set by the constructor and it’s had a very positive affect on our codes readability and reusability.

If you can't mutate, then all parameters need to be passed to the constructor. With the builder pattern, there is only one call of the constructor. But I still find it to be a pain if there are a lot of parameters.

Maybe with named method parameters, it's better, but Java does not have those.

Of course, lots of parameters are a code smell, I know. But what do I do? We have a business logic entity that always needs a creator (a user), a current owner (another user), the user who last modified it, a creation timestamp, a last modification timestamp, and a couple of other things. (And that's before we get to the actual data that's stored in the entity.)

Some people call what's in this example "sequential coupling":

https://en.wikipedia.org/wiki/Sequential_coupling

Having methods called "Initialize", in addition to a constructor, as a good indicator of sequential coupling.

This is why I LOVE to write interfaces for ORM:

Foo

Foo.Id

Now what is an ID? Just a long. But now when I call a function like getFoo(Foo.Id id) it is statically obvious what is going on.

Its little things like this that make it obvious what should happen vs documented and then yelling at you for not remembering the exact interface.

Reply on news.ycombinator.com