blog/content/thoughts/things-i-learnt-the-hard-way.md

+++
title = "Thing I Learnt The Hard Way (in 30 Years of Software Development)
date = 2019-06-10

[taxonomies]
tags = ["en-au", "programming", "work"]
+++

This is a cynical, clinical collection of things I learnt in 30 years working
with sofware development.

Again, some things are really cynical, others are long observations on
different jobs. 

<!-- more -->

## Software Development

### Learn to monitor

On a previous life, to understand how a system behaved, I added a ton of
metrics: how fast things were going in, how fast things were going out, how
many things were in the middle, how many the job processed...

It gives a really good view of how a system is behaving. Is the speed going
down? If it is, I can check what is going into the system to understand why. Is
it normal going down at some point?

Thing is, after this, it is really weird trying to figure out how "healthy" a
system without any monitoring is after that. Checking a system health with just
"Is it answering requests" doesn't fly anymore.

Adding monitoring early will help you understand how your system behaves.

### Unit tests are good, integration tests are gooder

On my current job, we do test modules and classes only (for example, we write
tests for the view layer only). It gives us some idea if things are going right
or not, but they lack a view of how the whole is going on -- a thing
integration tests, which tests how the system as a whole behaves -- do better.

### Tests make better APIs

We code in layers: There is the storage layer, which should make our data
permanent; there is a processing layer, which should do some transformation on
the data stored; there is a view layer, which has information on how the data
must be present; and so on.

As I mentioned, integration tests feel better, but testing layers by themselves
can give you a better view on how their API looks like. Then you can have a
better look on how to call things: Is the API too complex? Do you have to keep
to much data around to be able to make a single call?

### Future thinking is future trashing

When developers try to solve a problem, they sometimes try to find a way that
will solve all the problems, including the ones that may appear in the future.

But here is the thing: The problems from the future will never come and you'll
end up either having to maintain a huge behemot of code that will never be
fully used or you'll end up rewriting the whole thing 'cause there is a shitton
of unused stuff.

Solve the problem you have right now. Then solve the next one. And the next
one. At one point, you'll realize there is a pattern emerging from those
solutions and _then_ you'll find your "solve everything".

### Documentation is a love letter to your future self

We all know writing the damn docs for functions and classes and modules is a
pain in the backside. But realizing what you were thinking when you wrote the
function will save your butt in the future.

### The function documentation is its contract

When you start the code by writing the documentation, you're actually making a
contract (probably with your future self): I'm saying this function does _this_
and _this_ is what it does.

If later you find out that the code doesn't match the documentation, you have a
code problem, not a documentation problem.

## On a Team

### Code reviews are not fot style

Take your time on code reviews to point architectural or design problems, not
code style problems. Nobody really likes the person whose code reviews are only
"you left blanks in this line" or "missing space before parenthesis" and such.

Now, if you _do_ find architectural or design problems, _then_ you can add your
code style problems.

### Code formatting tools are ok, but they are no silver bullet

One thing a team may be tempted to do to avoid discussing style in code reviews
is to use a code formatting tool to auto-format code before commiting.

Now yeah, that kinda solves the problem, but there is one small problem:
we, humans, are not as flexibile to read code as computers are; what is
readable by a computer may not be readable by a human. Surely they try to
create some heristics on what is good for human reading, but that doesn't mean
it gets right.

If you _do_ use a code formatting tool, use it to find out where it changes the
code the most; you probably need to simplify that part of the code to avoid it
messing so much.