Collecting stuff from Mastodon to make a single blog post

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

@@ -0,0 +1,107 @@
++++
+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.