The importance of documenting things
Tags: programming, softwarecraftsmanship
Published: 2017-03-15 19:53:02

---
title: The importance of documenting things
published: true
description: What happens when someone asks you about your code and you cannot answer because you have no idea how it works? That happened to meâ€¦ again. This time I decided not to let it happen in the future
cover_image: https://cdn-images-1.medium.com/max/2000/1*DWIl2AmfeGEoWvOtc4TDpQ.jpeg
tags: programming, software craftsmanship
---

A few weeks ago a colleague asked me about a piece of code I had written.

Unfortunately I couldnâ€™t answer any of his questions.

## What was the problem?
The code was available, it was something we could call â€œself-documenting codeâ€, there were meaningful function and variable names, I did not use any clever tricks, there were tests. I think the assertions and test names were readable and could be used to figure out what I was trying to accomplish by writing the code.

But it was not enough.

## The code
The problematic code was an actor (if you do not know what it is, read about [actor systems](https://en.wikipedia.org/wiki/Actor_model)).

Let me explain why it was problematic.

* __I used the word â€œsynchronousâ€ in the actor name__
Actors are synchronous. An actor never performs two actions at the same time. You can create more instance of the same actor or use the actor to start processing something in a different thread, but one actor is doing only one thing at a time. So why did I call it â€œsynchronousâ€?

* __the actor was creating a JSON object and sending a HTTP request, nothing fancy__
Why did I need a separate actor implementation for something like that? What was so special about it?

* __it was using a non-blocking HTTP client__
It did not need to wait for the response. The actor could start sending another request even if the previous had not been completed yet.

* __the behavior of the actor depended on previously processed messages__
In Akka (and probably other actor systems) there are become/unbecome methods which allows you to change the implementation of the actor depending on a received message. 

My actor behaves in two different ways:

- When it receives a message, it sends a HTTP request and switches to a state in which it only awaits the HTTP response and cannot process new messages.
- When it receives a HTTP response (or an error), processes the response and returns to the state in which it accepts new messages.

## Why it was a problem?

There was nothing explaining what was the reason of it. No comments explaining why I wrote the code. It was not mentioned in the documentation.
When the colleague asked me about it, I could not explain it, because I had already forgotten everything.

It seemed I had seriously over-engineered the code for no reason. I was trying to prevent actor from sending too many request to the server at the same time. In this case â€œtoo manyâ€ means more than one. That was the obvious part.

## Why?

Why the server could not handle more messages?
Was there a real reason or was I too careful?
I have no idea.

## Break things

We could assume that there is a valid reason for keeping the code and do not touch it. We could be afraid to remove it, because â€œsomething may brake and it is going to be our faultâ€. Fortunately, we know we can restore the previous version of the service with a single click of a button.

There was no reason to keep the code, nobody knew why it is there, hence we removed it andâ€¦ nothing happened.

I am absolutely sure there was a reason to write that code when I was writing it. Now I know that we no longer need it. Orâ€¦ maybe we do? Maybe one day something is going to fail because of that change.

If it happens, we are going to restore the old solution and document it properly. For now, there is no reason to keep it and waste our time every time we read unnecessary code.

## Why you need comments?

It should not happen, I should not need to experiment with the software to check why the code exists. Decisions should be documented. Can we just start writing comments?

The comments should not explain what is your code doing or how it is doing it. You have the code and its tests for that.

What I need in comments is an explanation why I should not remove that code. If you have made a decision that affects the architecture of the application, please tell me about it in the comments. If you have tried a few different approaches before writing the code, tell me about that. So I do not waste time thinking â€œmaybe we should have done it differentlyâ€.

I hope I will remember about itâ€¦


This text has been cross-posted from: [mikulskibartosz.name](https://mikulskibartosz.name/the-importance-of-documenting-things-5d989b2797ba#.nu8yoavjn)