Design by error

A well-designed error helps fix bugs

Traceback (most recent call last):
File "/usr/local/lib/python3.8/asyncio/", line 81, in _run, *self._args)
File "/usr/local/lib/python3.8/site-packages/aiormq/", line 115, in <lambda>
future.add_done_callback(lambda x: x.exception())
Error during render of workflow [REDACTED]
Traceback (most recent call last):
carehare._exceptions.ConnectionClosedByServer: RabbitMQ closed the connection: 501 FRAME_ERROR - type 3, all octets = <<>>: {frame_too_large,160193,131064}

The most important part of every API is its errors

Users have features; programmers have errors

… and now, some shade for Python asyncio

The Rules of Errors

  1. Obey your programming language. Java, Python and Ruby use Exceptions. Go uses “errors”. C uses errno. Rust uses Result. Scala uses Either. Don’t waste everyone’s time writing Results in Python or catching panics in Rust.
  2. Design for all possible errors. If you’re using a network, design for disconnects. If you’re writing to disk, design for failed permissions and full disks. If you’re accessing the database, design for an SQL error. And remember: you can have two errors at once.
  3. Design error abstraction layers. An HTTP library should treat ClosedConnectionException and SSLException as distinct errors. A Twitter API wrapper can probably treat them all as IOException. Many languages use inheritance for this.
  4. Document every function’s errors. Emulate Java’s API documentation (example): for every function, list all the possible problems, what they mean, and how to fix them.
  5. Plan what happens next. Should an SSL error crash an app? Decide! Write documentation and error-message text to suggest what your hapless reader should do next. Make stack traces are legible. If an error causes another error, help the programmer log and address both.
  6. Test each error. Unit tests are quickest. They prove that a programmer who experiences the error can see it and handle it.

And then … you’re done!




Journalist, ex software engineer

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Journey of a link in Rails

Why does a BT’s height equal log n?

My Journey into Software Development

Learning How To Code Fast

Test Driven Development(TDD) in Django and Django REST Framework (DRF)

Mobile Editing on iOS

Hacking Oracle TNS Listener

Project 4: ESP 32’s External Sensor

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Adam Hooper

Adam Hooper

Journalist, ex software engineer

More from Medium

What are Cookies and how they affect us

Basic concepts of github actions and continuous integration through github actions.

Stateless-ish Authentication

How to organize your project semantically? 📜