Deliberate coding

I wanted to share an important lesson I learned from my colleague Ramon de la Fuente. I was explaining to him how I made a big effort to preserve some existing behavior, when he said something along the lines of: the people who wrote this code, may or may not have known what they were doing. So don't worry too much about preserving old stuff.

These wise words eventually connected to other things I've learned about programming, and I wanted to combine them under the umbrella of a blog post titled "Deliberate coding". Doing something "deliberately" means to do it consciously and intentionally. It turns out that not everyone writes code deliberately, and at the very least, not everyone does it all the time.

Decisions

It turns out that, when I look at a piece of legacy code, I'm making a few assumptions:

• Every line of code is there for a reason, it has been explicitly decided that it should be this line of code. E.g. it embodies a piece of domain knowledge the developer had gained, it represents an exact requirement as provided by the product owner, it's a fix for a bug in some exotic situation, etc.
• Every aspect of the behavior emerging from the code is relied upon by at least one user. Whenever I change something, it should be refactoring in the true sense of the word: changing the structure of the code, without changing its behavior, so the user isn't put off the track.

As I write this out, these are clearly not such good assumptions. Whether or not we can trust the code to be meaningful, important, to have been deliberately written down - that depends on a lot of things:

• How were the developers "managed"?
• Did they actually speak with domain experts?
• Did they use some kind of test-first approach? Did they think about testability?
• How well did they know the programming language itself?
• Did they have a step-debugger installed?
• And so on...

This could be a very long list actually.

Documenting the intention behind the code

I remembered something Cyrille Martraire wrote in his exhaustive treatise about the topic of "Living Documentation":

Building software is about continuous decision-making. Big decisions usually get a lot of attention, with dedicated meetings and several written documents, while other "less important" decisions are somewhat neglected. The problem is that many of these decisions end up being arbitrary rather than well-thought about, and their accumulated effect (perhaps even a compounding effect) is what will make the source code hostile to work with.

Maybe over time, the decisions that the programmers made were not always made consciously. Maybe, they were not based on domain knowledge, or actual requirements. Possibly, a line of code is just there:

• Because adding that line seemed to make it work,
• because the same line was also there in a similar situation,
• because a manager told them to add it,
• because it was a copy-paste error, or an accidental Duplicate line keystroke (remember goto fail;?)
• because it was a leftover of the old situation, or maybe
• because a manager didn't tell them to remove it.

This is why the intention behind the code needs to be documented. The code itself could be its documentation, and so could the history of the code, as it is recorded by your version control software. But tests/specifications are the best things to happen to code. Without tests, lines can be added, modified or removed and the developer who later reads the code, won't know if the code (and all of the code) is there for a good reason.

Writing code consciously

So I learned not to trust every line of code I encounter, and not to preserve all of its little (weird) behaviors. But, how to make sure that people who come after me can trust my code? Or, generalized: what can any developer do to write code consciously?

Well, the answer is a big one. Follow clean code rules, adopt a test-first approach, apply Domain-Driven Design, with related practices like Living Documentation. Anyway, it'll be impossible to cover all of these rules in this article. I thought it would be interesting though to briefly discuss some programming practices I noticed over the past few years, that stand in the way of deliberate coding.

Examples of non-deliberate practices

If you're looking for things that stand in the way of deliberate coding, keep an eye on the things yo

Truncated by Planet PHP, read more at the original (another 6346 bytes)