From 061ec16a156de579c6ea8b376a6dc4a3033a70d9 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Mon, 10 Jun 2019 21:40:36 -0300 Subject: [PATCH] Collecting stuff from Mastodon to make a single blog post --- .../thoughts/things-i-learnt-the-hard-way.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 content/thoughts/things-i-learnt-the-hard-way.md diff --git a/content/thoughts/things-i-learnt-the-hard-way.md b/content/thoughts/things-i-learnt-the-hard-way.md new file mode 100644 index 0000000..c604c92 --- /dev/null +++ b/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. + + + +## 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.