Labors of the Fastidious Coder

I spend a lot of energy on the coding equivalent of the mantra "cleanliness is next to godliness".

People sometimes think this is extra work but it's not. In fact, it's anything but that.

Fastidious coding is frontloaded work. That is, I'm taking the thing that I know is hardest - keeping my design natural to my problem - and doing that work as soon as I can.

When you do that, code-cleanliness work doesn't start to stack up into a seemingly insurmountable pile.

That psychological effect, alone, is worth the "effort" but there's a subtler, more potent source of value.

Badness compounds on badness. When you let code be bad, you do bad things to get it to work. That makes the code worse.

So, allowing a quality problem to fester not only accumulates redesign work into large chunks but also accumulates work you would never have had to do if you just kept things clean.

Following is a video wherein I spend about an hour cleaning up a test library, among other things. You can think of it as a waste of time or an expression of my perfectionism if you want to, but I would like to offer a different perspective.

What if you watch the video and try to think about all the things that could go wrong if I didn't do that cleanup, this morning?

Excerpt from Live Coding Session

Following is a little monologue I delivered via comments in my live stream.

// I woke up having realized
// again, the problem is an artifact
// of not dissolving the problem into
// enough tiny pieces.
// we need one thing that posts a pending state
// whenever the interior state changes
// we need another thing that expires a interior
// state after a period of time
// we need another thing that transitions to the right
// new state on tap start (for double tap)
//
// cohesion
//
// it's always cohesion
//
// every time you see some other force that looks like
// it's in contention with cohesion, it's really not.
// it's that you don't have enough cohesion...

It's never that you broke things down too far.

The Importance of Deleting

At the end of my ride to my current client's office, I ruthlessly hunted down and destroyed a class I didn't need anymore.

It wasn't doing anything. It wasn't bad. I just wasn't using it anymore.

It was in a category of classes that suggests I might need it, too. So this might seem overly fastidious to some. Maybe they are even right.

My observation is that dead code turns to gangrene remarkably quickly. Removing it costs little and pays off big way more often than the reverse is true.

For Encapsulation, Ask "What's the Cost of Changing Visibility Later?"

Most languages give you a choice regarding how visible a member of a class will be. The choices vary from language to language but, typically, they range from more-widely exposed options to those granting narrower visibility.

Every time you define a member, you are making this choice. Even if you take the default level of visibility, you are still making the choice to accept the implicit level of visibility.

One thing you can do to inexpensively start improving the level of encapsulation in your system is to start asking a simple question:

What's the cost of changing visibility later?

Generally, all levels of visibility have the same cost, initially. You aren't going to choose an access-modifier that prevents something from being used the first time you write it.

What really matters is how the level of visibility will interact with change. If you make something too private, now, how hard will it be to make it more public, later? If you make it too public, now, how hard will it be to change it to be more private, later?

In a lot of cases, it's pretty straightforward but it isn't always obvious. That's why it's worth asking the question.

Simple Is as Simple Does

Simplicity has no relationship to how many code structures are written or boxes are drawn. It has nothing to do with whether or not a particular person can understand some code. There is no relationship between how many "things" you can count in a system and how complex it is because it all depends on what you decide counts as a discrete "thing".

A good yardstick for simplicity, in software, is sustainability. Code that stays about as easy or hard to change over a long period of time is probably simple code. Code that gets harder to work as it evolves is overly-complicated.

Code qualities are proxies for true simplicity. They guide you because they correlate strongly with sustainability. Use them. Talk about them. Weigh them when considering your design changes.

If you want to make a change to your design and it's going to make your code easier to work with over time, don't let someone complaining that it "adds complexity" dissuade you. If you're blindly following a "best practice" and someone has a compelling argument for how it's going to make things harder in the future, you're probably adding complexity.

Design Patterns and Code Qualities

A friend of mine recently intimated that we don't need design patterns because all the principles and patterns can be derived from code qualities.

It's true. Patterns can be derived from the principles of code qualities...the same way aerodynamics can be derived from quantum mechanics.

Macrocosmic Code Qualities

As I've mentioned before. I think all software work is design work. I also have a relatively context-insensitive definition of code quality.

The code qualities to which I (and many) subscribe can apply at any level of design.

If you're writing a method, you can ask yourself any of the following...

• "How strongly-related are these instructions?"
• "How will I know when this is done?"
• "How easily will it be for my future-self to comprehend this?"

The same qualities translate into class-level design as different questions...

• "How strongly-related are the members of this class?"
• "How will I know that this class works as intended?"
• "How easily can I understand how this class fits into the larger design?"

The same principles apply all the way up to the very largest scale of software design and all the way down to the lowest-level detail.

This is one of the things that is great about these code qualities. They are general rules that are aligned with effects.

Cohesion matters because it defends against a certain kind of coupling, makes testing easier, and makes code easier to understand. It matters the same amount and for the same reasons at any scale.

There's something aesthetically pleasing about that.

For Coupling, Ask "Is There an Hidden Relationship?"

Today's code quality question pertains to coupling: "Is there a hidden relationship?"

The most dangerous kind of coupling is that which you don't know is there. If you find yourself writing some code and you can't explain why you're doing what you're doing just by reading the code around it or the tests, you probably have implicit coupling.

So be vigilant. As you write new code, maintain old code, or review others' code, ask the question "Is there a hidden relationship?"

This is a tricky one. You're not going to catch it all the time, at first. That's okay. If you can prevent 10% of the implicit coupling you otherwise would have written or clean up 10% of the implicit coupling you otherwise would have passed by unnoticed, it's a win.

For Coupling, Ask "Does This Express a Semantic Relationship?"

There are two kinds of relationships you can form from a class:

1. The fulfillment of a semantic need.
2. The exploitation of an implementation detail.

The former kind of relationship is far more resilient than the latter.

There are a lot of reasons why this is true.

The most compelling argument is the asymmetric relationship with change. A change to what you need invalidates an expression of both what to do and how to do it. A change to how something should be done, on the other hand, is unlikely to invalidate what need is being fulfilled.

So today's code quality question is "Does this express a semantic relationship?"

The Bizarre Properties of Coupling

Coupling is one of the easiest code qualities to mistake because of its unusual properties.

For one thing, Coupling doesn't require that you have to do the work to find the consequent change but t also doesn't preclude the possibility.

For another, coupling isn't always obvious.

Redundancy vs. Duplication Examination - Method Calls

Previously, I wrote about redundancy and how it differs from duplication.

I'd like to dig into that situation a little with an example. Imagine a design where one class provides a method used by many others.

A basic static structure diagram

Redundancy - Replication of Purpose that You Might Have to Find

I’m sure there are plenty of definitions of redundancy. A naïve definition might just try to make it a synonym for duplication.

Duplication isn’t really a problem, though. Certain acts of duplication are the cause of certain redundancies – for instance, copy-pasting a method – so it’s natural for us to blame duplication for our problems.

Yet, even though it is sometimes the cause of a problem, duplication is not, in and of itself, a problem.

The problem exists when you need to make the same change to two or more things. Specifically, it’s a problem when you need to find two or more places to make the same change. The reason why it’s a problem is that you run the risk of missing one of the places where you need to make a change and you almost certainly will expend a lot of energy trying to mitigate that risk.

More on this to come.

The Readability Lament and How to Handle It

This week, I've written a lot about readability. It isn't really a property of code. It's actually a quality of an observer's experience when working with code. Yet it's very, very important.

The combination of potency and interpretive license provides a potential exploit for developers resisting the adoption of technical excellence. Just say "that's not readable".

Readability is a Tricky One

Readability is subjective, rather than objective. What's readable to you may not be readable to me. In kind, what's readable to me might be gibberish to you.

In fact, I've even seem someone transition from believing that object-oriented designs are unreadable while procedural code is readable to the exact opposite opinion. At the end of a few years training and study, he considered object-oriented designs to be easier to understand and procedural designs to be inscrutable.

Readability, an Essential Code Quality

Readability is an important code quality.

In fact, it is absolutely-critical. If a team can't understand the code they maintain and extend, then they can't really maintain or extend it.

That's just the difference between "some readability" and "no readability". While it's possible to create inscrutable code, it's more common to write code that is difficult, but not impossible, to understand.

Code Quality Deficiencies Demand Root Cause Analysis

Looking for code quality problems and then fixing them is really just another form of trying to test quality into a product at the end of the development process.

This simply doesn't work. Problems have root causes and. So long, as those causes are allowed to persist, new problems will continue to arise.

Objective and Subjective Code Qualities

Some code qualities are objective and others are subjective.

I don't mean this in the colloquial sense of the words. I mean it in the actual sense of those words. Objective qualities are qualities which are properties of  the code itself. Subjective qualities are qualities which only exist as part of a developer experience.

For Coupling, Ask "How Intentional Is This Dependency?"

Coupling needs to be controlled. One way to do that is to evaluate whether or not any given instance of coupling is viable.

Today's code quality question is this: "How intentional is this dependency?"

Note, it's not about how intentional the dependency looks. It's about whether a dependency actually is something you meant to put in place or just an accidental tag-along from what you really wanted to use.

Code Quality Questions

If it hasn't already happened, you will eventually develop your own sensitivity to the various code qualities.

While you are practicing, though, it is useful to have concrete, diagnostic questions you can use to determine the health of your design decisions and to guide your future choices.

To that end, I will start writing a number of entries tagged "code qualities question". Each entry addresses a single question you can ask yourself to help you analyze a single aspect of a single code quality. These entries start today.

Control is the Goal with Coupling

The code qualities aren't all unconditionally good. Nor are they bad. They just are. The effects are good or bad but not the qualities, themselves.

Coupling is one of the greatest examples of this fact.

You can't set a goal of eradicating coupling because certain kinds of coupling are essential to software design. You can't set a goal of creating coupling because rampant coupling makes a system all but impossible to maintain.