Document What You Do, Do What You Document

I was asked to look over someone's code this evening on a personal project that they had been working on. So, naturally, I asked for their documentation and looked for code comments.

There were none.

I just emailed the organization back and told them not to waste my time - particularly when their 'software engineer' was still with them. Sure, it's pro bono work that was done. Sure, I was doing pro bono work. But really, life is too short for that kind of crap.

And thus begins my rant. It's not a new rant of mine, but it has become more refined over the decades.


I have encountered the issue. I've seen it on IBM System 36s, IBM 360 Mainframes right on up to that annoying device you have that makes sounds and vibrates when someone wants to get a hold of you.

Documentation is what separates the rabble from those that don't go extinct. If you watch this video (1 hr) - or you can take me at my word for this quote on the evolution from hacker to engineer:

A hacker can come up with solutions, but maybe they can’t look back after they’ve finished and realize how they came up with the solution. They just kinda poke at things until they get something that works.

At some point, you level up and become a developer and a developer understands best practices. They’ve heard other developers say things like “you should put your scripts at the bottom of the webpage” … and you use those best practices to craft solutions but you don’t really understand beneath the best practices, beneath the abstractions.

An engineer is someone who can get things done, craft a solution — they understand the best practices, but they also understand why they’re using the best practices that they are … [they] move into an understanding of the platform as a whole.

Documentation is a best practice. Any time I see code without documentation, I see the work of a hacker - not a developer or engineer and I take umbrage when someone has the audacity to call themselves such (or is called such) without documenting anything. It tells me that they haven't been around long enough to look at their own code and be lost. It tells me that they don't care what kind of house of cards they build to maintain. It tells me that they don't respect the people that will come after. It tells me that they thought so highly of themselves that they thought their code would never need to be maintained. It reeks to me of 'amateur', no matter how good the code is. It tells me that there was no process involved with the code, that there were no best practices and that others let it slide.

Sure, documentation is not the most glorious aspect of Software Engineering or Software Development. It's annoying, particularly when you're doing software archaeology and have to document what someone else has been doing and hoping you get it right. Sometimes - most of the time for me - it's been my job to make sense of things that make no sense. This is the sort of nonsense that has countries other than the U.S. protecting the use of the word 'engineering' in a title, and years ago I reached the point where I wish the U.S. would comply with it.

If you're just going to write code and not comment or document anything, it used to be called job security. There are still niches of this sort of lazy 'protect my job' sort of stuff out there, but... for a project to survive in this day and age requires not bleeding money in wasting time figuring out how something should work. It's a financial hemmorage in the maintenance aspect of the lifecycle all because of a lack of best practices. It means that others that come in will have to spend more time (read: money) to figure out how to fix the perfect code you wrote.

Hiring a coder? Yeah, when you get the code, make sure it's documented. Or don't pay.


Measuring Quality

On metricsAside from demonstrating just how much of a geek I am when I wrote 'Know How You Measure', I opened the door for a few people that know me fairly well to ask me why I spend 'so much time' measuring things like... mileage. In the context of a gearhead car geek, it's simple.

You can tell when things go wrong, as well as tell if what you do is an actual improvement. It's really that simple.

As Peter Drucker wrote, "You can't improve what you can't measure." You can think you improved something - like, for example, the air ram or, as they call it these days, 'cold air intake'. It's been proven (there's a video in that link) that it pretty much doesn't work (in a stationary vehicle on a dyno - 'know how you measure', right?). We all have theories on how things can improve, but in the end we have to take into account whether or not something is an actual improvement. How do you do that?

You establish a baseline. It's where everything starts. True gearheads do it. Engineers do it. Doctors do it (why do you think they do all those tests and x-rays?). Everyone who wants an improved result has to at first have a result to improve upon.

But it's not just improvement. It's also about catching failures. In the example I gave in 'Know How You Measure', the main reason I track mileage is not because of improvements but because mileage is a good indicator of whether something is wrong, particularly in a complex system. It's an integral part of maintenance as well as development.

In summary, it's about measuring quality, where quality is easily defined for a man-made system: Works as designed.

Know How You Measure

"Measure a thousand times, cut once"Last weekend, I put new tires on the car (no, not the RX7 which has since been sold, but the Subaru). And my mileage seemed to decrease. Yes, I'm the sort of person who keeps a running tab on the vehicle so I know when something is going wrong. Spreadsheets and everything.

A cursory explanation might be that the tires are heavier, but that's easily dismissed (or should be).

Clearly, something changed with the tires. But before we delve into that, it's important to understand how I calculate my mileage - every fillup - and what affects those things.

The way I calculate my mileage is by writing down my odometer reading at every fill up and dividing that by how much gas I use to fill up. I fill up at the same station every time so that variations on the fuel pump flow are minimized (in fact, really, I typically use the same pump at that station). The odometer reading - I have a mechanical odometer - comes directly from the transmission, and I've done nothing to the transmission. The spinning of the output shaft of the transmission, probably at the ratio of 1:1690, spins the odometer.

This means that for lower mileage, the output of the transmission would be spinning slower over the period between fill ups since it would show less fill ups. Think range of the vehicle on a tank of gas.

Odometer reading/gallons = mileage; => Odometer reading = mileage x gallons

So what could cause the engine to be burning more gas? Resistance is the first thought, so I checked the oil and transmission fluid. They're fine. The odometer seems to be in good shape, but that's part assumption. What changed? The tires. And what changed about the tires?

2 things changed about the tires. The tire tread is much better, which means effectively the diameter of the tires has increased. The tire inflation is proper (they weren't before because I spend time in sand and also because the tires were old and hard and I wanted more grip on the pavement). So if the tire diameter effectively increased slightly, that means that for every rotation of the transmission output shaft, the car goes a small amount further.

That, in turn, makes it look like the car is traveling less distance on the odometer which makes it look like the mileage has decreased. It hasn't. I crunched the numbers and the mileage, which itself is relative, simply shifted a small amount and showed a small but noticeable decrease in my calculated mileage.

And thus, you have to know how you measure things. I've seen it in electronics (uncalibrated instruments) and software engineering (no baseline). I've seen it in just about every setting imaginable - even in the medical field.

Knowing how you measure something is even more important than measuring it.