Voo-doo constants without comments suck.

Voo-doo constants are the numbers almost every engineer meets in day-to-day work. While reading “Operating Systems: Three Easy Pieces”, I saw a mention of “Voo-doo constants”, and to quote the authors:

they seem to require some sort of black magic to set them correctly

When I read it, I couldn’t help but to think about how often I see them in my daily work. At Sentry (that’s where i currently work), the codebase is full of them, some examples are:

• timeouts
• maximum allowed values
• number of retries
• duration of delays

These numbers, really seem like a black magic, since they almost never have a comment on how we came to that value.

Comments prevents problems

We can all agree that it’s impossible to completely avoid them, sometimes it doesn’t really make sense at all to spend a lot of time measuring and fine tunning these numbers, so they just need to be set by the gut feeling.

The problem is, when I see a magic number, I have no way of knowing if there is any deep reason behind it, or it was just the gut feeling that produced this number. That makes it hard to change it when we need it, for example when our async processing task starts being run on a bigger datasets and starts timing out. One of the first quick fixes many of us would do is to increase the timeout of the task.

Often, that solves the problem, but what if that timeout had a very good reason to be set to exactly that value? Without the comment noting it, it’s very hard to know it (unless you know your system super well). Sometimes, changing that timeout value might lead to serious problems in the system, perhaps our async task is being run by the service that can’t handle long running tasks, and now we have a noisy neighbour problem causing trouble in all other async tasks that our product needs. Maybe that async task should have never even been processing that much data in the first place, but it would be nice learning that without bringing the production down first.

And the prevention of the problem above is simple. A short comment mentioning that timeout is at the maximum value we are confident our system can handle, it would be a good pointer for other engineers to be extra careful when considering changing it.

So if you think that the Voo-doo constant you put somewher is important, please add a comment mentioning that!