The other day I described CRAP, which is a metric that flags code that is risky to change. I suggested that if you need to change that code, you start with tests and refactoring.

Tests and refactoring are positive to the codebase and improve the readability of the PR they are in, which is why I like CRAP as a metric—it’s hard to game.

In contrast, Story points (and velocity based on it) are the exact opposite.

Story points are completely made up numbers that have low accountability. Velocity is just points-over-time, so it’s also made up. If a team must improve velocity (for their manager), the easiest thing to do is to over-estimate the points per task and like magic, velocity can meet any target. I don’t think engineers would do this consciously, but this is just a known phenomenon of metrics (see Goodhart’s Law).

This is one of the reasons I don’t use Story Points. But to be honest, almost any estimation technique is ripe for gaming (ala Scotty from Star Trek).

When I wrote about DevEx, a new developer productivity methodology, I wrote that I thought that they “do help engineers deliver software better and faster”, but that they are most useful to the team itself (not stakeholders).

Looking over that article I realized that the thing I like about these metrics is that they are hard to game. If I get several 3-hour blocks of uninterrupted coding time per week, then I am sure I can write more and better code than if I didn’t. Counting lines of code (and judging its quality) is fraught, but hours of uninterrupted time is easy to count and more is better.

If you are worried that coders will shirk other duties (like code reviews or attending meetings), there is another metric to measure feedback loops, which is in tension to the flow metric.

My main critique of DevEx still stands—it’s not something to report outside of the team. But the more I think of it, the more I like it and will try implementing it on my (1-person) team.

The CRAP metric combines cyclic complexity and test code coverage to flag functions that are both complex and under tested so that you can see which functions are risky to change.

There are extensions for many IDEs to get you the metric directly or that will show the parts (test coverage and complexity). But you don’t really need them, because you know CRAP-y code when you see it—run unit tests to see if the function is under test and eyeball the complexity by counting up the branches and logical sub-expressions—you can stop counting at about four, because more than that is probably CRAP.

So, if you have to change a CRAP-y function, you could start the PR by trying to lower the score.

The first step to reduce CRAP scores is to add tests. Complex functions are often hard to test, but I would add any tests you can to start, because they help with the next step.

Next, lower complexity by refactoring the function down into simpler parts. The tests you just added will make sure you do it right, but these should be simple mechanical refactors that might even be automatable by your IDE. If they are not trivial, you need to add more tests. Do not restructure or rewrite code unless that’s the goal of the PR—all of your changes should preserve the observable behavior of the code.

I start a lot of PRs this way. It’s a good way to get warmed up, and you know that you are improving the code base in a place that benefits the most from it. You are paying technical debt down right before an interest payment was due.

Don’t talk about refactoring club.

A long time ago, I linked to this post by Martin Fowler (author of Refactoring), where he lamented at the misuse of the word “refactoring”:

However the term “refactoring” is often used when it’s not appropriate. If somebody talks about a system being broken for a couple of days while they are refactoring, you can be pretty sure they are not refactoring. [This is] restructuring.

For me, refactoring might be part of every PR. My first commit is often a refactoring that makes the rest of the commits easier to do and understand. I might also refactor at the end, but those commits will be squashed before I PR since you don’t need to see how I got there.

In TDD, there’s a specific practice to Red, Green, Refactor your way to working code (or as I do it Green, Refactor, Red) that explicitly thinks of refactoring as a small thing you do often.

The tell to knowing that you are doing refactoring wrong is that you feel like it’s something to talk about. Refactoring, when done well, is about as interesting as variable naming.

It’s not not interesting, but you don’t need to talk about it in a stand-up.

I recently reread Peak by Anders Ericsson, which is the source of the term “Deliberate Practice” that was popularized by Malcom Gladwell’s “10,000 hours”. The truth is more complicated, and I highly recommend reading both Peak and Kathy Sierra’s Badass, which deep dives on the practicalities of gaining expertise.

I wrote some thoughts on applying deliberate practice to learning how to code a couple of years ago. Looking that over, I was very focussed on what I thought you should do, which was to turn vague descriptions into code (not transcribe code tutorials). I had not remembered another important point, though. One purpose of the training is to help build a mental representation that makes it easier to do the task.

One of the mental representations I have is that UI layouts are primarily about nested rectangles and the relationships of their sizes and positions to each other.

If I were learning to code HTML/CSS now, I would try to learn this first and only make pages of different colored rectangles in common layouts. I would try to limit CSS to just the layout attributes and the HTML to just <div> and maybe just enough to see the layout.

Next, I would add the concept of invisible rectangles that are just helping with the relationships.

Next, we could explore media query breakpoints and other responsive features of web coding.

Only then, would I attempt to make “real” pages. And, I would start with getting the layout done first.

The key is to identify the mental representation that helps to do the harder task and to break it down to a simple task that you drill over and over to make it automatic.

SQL is a well-established standard and is implemented in a consistent way across a variety of DBMS’s. In my career, I’ve worked with MySql, SQLServer, SQLite, and Oracle. My knowledge of SQL goes over pretty unchanged.

My code for all of these systems is hopelessly incompatible.

I can’t grab SQL from my node app and put it in my iPhone app, because there’s more to it than the SQL. The SQL is embedded in the host language and often abstracted in a library (like TypeORM, Django, CoreData, or JDBC). These languages and libraries are completely incompatible with each other. I tend to use ORMs, but this would be true even without them because you often want some kind of composability with your SQL clauses. You’d have to build that in the host language and then spread partial SQL strings around your code.

Even if you tried to keep your SQL pure and outside the host language, you’d run into portability issues. Each of the individual DBMS vendors add to their implementation of SQL in mutually incompatible ways (mostly for good reason). User needs often outpace the speed of the standardization bodies, and so the vendors need to innovate outside of the standard.

You run into this with web programming because there is no standard way in SQL to grab rows N through M from a SELECT. In order to implement paging, you need to be able to do this efficiently. SQL has also been extended in incompatible ways to store external blobs. Even simple things, like dates, are not consistent.

And, I haven’t even mentioned stored procedures.

But, even though SQL doesn’t help me port my programs, SQL is a good way for me to think about data. I can show it to other developers or DBA’s, and we can have a conversation. Most of my data code will be based around SQL in some way and will be understandable to any developer who knows SQL.

My programs get many benefits from SQL, but not portability. And this is true with standards in general. Instead of Java’s promise to “write once, run anywhere”, we live in a world that React Native calls “learn once, write anywhere”, and it’s not bad.