DevOps, Living Documentation, and Hexagonal Architecture

Struggling with Legacy Code and not enough time to clean it up?
⛑️️ My First Aid Kit can help you rescue any codebase quickly and safely!

On September 22, 2021, I co-organized the 7th edition of The Legacy of SoCraTes with my partner in crime Adrian Bolboacă.

It’s a half-a-day remote conference where 5 speakers share their tips to deal with Legacy Code.

The Legacy of SoCraTes by Nicolas Carlo and Adrian Bolboacă

This edition raises discussions around topics we never talked about before: legacy pipelines and Living Documentation. We also had an inspiring talk that relates Interior Design with software development.

Finally, Jim Humelsine did a tour of the Hexagonal Architecture and how to approach legacy codebases with this in mind.

As usual, we recorded all the talks so you can watch and share them with your friends and colleagues!

Working with Legacy Pipelines

Laura Santamaria is reaaaaally well-versed into pipelines. She’s really involved in the DevOps community and I was glad she came to share her expertise on this crucial topic.

Indeed: you can’t really tame a legacy codebase if you can’t easily deploy changes to production in the first place!

When you inherit a legacy system that you now have to maintain, you should ask yourself the question: what does it take to make a change… and get it deployed?

Turns out the pipeline is probably as legacy as the code. You should maintain that too!

In her talk, Laura gives precious advice to doing so:

A few gems that really stood out for me:

  • When you are lost, make a map! 🗺
  • Priorize stability when modernizing the pipeline. Don’t let users notice it’s being changed!

These are true for code as well:

Software Interior Design

AKA: limit cognitive waste when writing code

EsterDaniel Ytterbrink has a blog with an amazing title: 🍫

In their talk, EsterDaniel is comparing taking care of your codebase as taking care of your home. I think it makes sense: you spend a considerable amount of time in this codebase. Paying attention to the details will preserve your sanity.

You may have inherited something particularly complex. That’s fine. You can reverse the steam. Slow and steady progress over time does wonders!

Don’t let a wrongly placed bureau hurt your toes again.

Don’t let a wrongly named variable waste your time again.

Things that help:

  • Define standards
  • Make them explicit
  • Refactor code towards standards
  • Separate Queries (= return something) and Commands (= execute something)
  • If something surprised you, do something

Leaving Documentation, or Living Documentation?

Writing documentation is hard. It’s only a matter of time before it gets outdated with what the system actually do.

Cyrille Martraire has worked on this problematic a lot. He wrote a book titled “Living Documentation”. This talk is an excerpt of what you can find in his book.

There’s a lot to unpack in this talk. One of the key aspect of Living Documentation is to generate it from the code itself. You can use tags and annotations to do so.

Parsing and extracting such tags are explained in the book. There’s no standard, but it’s not that hard to do. If you’re looking for generic tooling to do so, then you’ll enjoy our next talk…

Writing Maintainable Documentation with Automated Tools

Dr. Ana Clarkson is the creator of Dexy, an open-source software for software documentation, reproducible research and document automation.

In her talk, she explains how she’s able to generate Living Documentation from any codebase with her tool. It seems to be flexible enough to adapt many situations! In particular, it can run in your CI pipeline — which is great news.

Hexagonal Architecture & Legacy Code

Finally, I was happy to have Jim Humelsine come and talk about Hexagonal Architecture.

The core concept behind this architecture applies to any software. The key of taming a legacy codebase usually goes by identifying the Infrastructure parts, extracting them from the Domain, and invert the dependency.

If you’re not sure what I’m referring to, then I recommend you watch this talk. Jim explains everything:

“These talks are really great! Can I have more?”

Sure thing!

There’s no fixed schedule, but I like to organize this short conference every few months. I reach out to a few speakers to build an interesting agenda, then we set up the event.

Everything is FREE. Attending is the opportunity to directly ask questions to these speakers, from the comfort of your home.

If that’s something you want to hear about, subscribe to my newsletter below 👇

I publish my monthly tips on Legacy Code here. I also tell my subscribers in advance about the conference and the agenda, so they don’t miss out. Join them!

Nicolas Carlo

Written by Nicolas Carlo who lives and works in Montreal, Canada 🍁
He founded the Software Crafters Montreal community which cares about building maintainable softwares.

Similar articles that will help you…

Delete unused code (and how to retrieve it)

Dead code adds noise to the codebase and should be deleted. Yet, deleted code feels harder to retrieve. Here's how to find such code easily with git!

3 must-watch talks on Legacy Code

I have hosted more than 37 speakers to talk about Legacy Code tips and tricks. Here is my top 3 of the talks you should probably watch!

The key points of The Programmer's Brain

This book analyses how your brain works and gives concrete advice to help you work with Legacy Code. Here's my summary of its salient points.

Testability, Empathy, and Safe Refactorings

4 great talks on Legacy Code that I had the pleasure to host. This edition particularly focuses on testing and refactoring.

← Find more tips to work with Legacy Code