Understanding code under change

Why is it so hard to jump into a team and start contributing to code? Why is someone else’s code so darn incomprehensible?

One reason is that the code is a snapshot of a system in process. If you know where it was and where it’s aiming, the middle makes more sense.

For instance, I’m working on a system that lists steps between code push and deployment, then executes them. We started out using GitHub statuses for this, as the simplest thing that could work.

Now that we are sure this is useful, we want them to be their own thing, a Goal in our cortex (graph database). We’ve started by creating a custom cortex Goal event, and creating Goals for every push. We copy those to GitHub statuses, and the rest of the program works off those. Incrementally, I’m changing code to use Goals instead of Statuses. If you came into the code at this point without that background knowledge, you’d find it totally confusing. Why do some things update Goals and others Statuses? How do those even connect? What kind of loon wrote this convoluted mess?

If you’re the person who has been around long enough to know where the code was, and if you understand the desired architecture it’s moving to, be kind to people without that context.

If you’re the person reading ridiculous code, seek out someone with background and ask them. There’s probably a story about this code, both from its past and its future. Then you can contribute to moving toward that future, and eventually to closure.

As soon as everything is saving Goals and triggering off Goals, then it’ll copy only a few to GitHub statuses for visibility, and I’ll delete the duplicitous code. I’m off to work on that now before something else super urgent pulls me away and the code gets stuck in this icky swamp forever. (Been there?)