Keeping track of key decisions

There are some seriously old software projects around these days. Take SPSS which was first released in 1968 and is still updated. When a new person joins the SPSS team, how do they learn what has already been tried before? Are they bound to repeat bad ideas of the past? Is there a reference to tell them their idea was already explored and discarded in 1983?

You don’t need to have 50 years of project history to wonder how a project arrived at the status quo. Even if your project is just a few years old, new hires ask about past decisions. Often people who were on the team at the time of a decision can not recall why a decision was made the way it was made.

I have noticed that development teams seem to be focused on the future. Their process, documents, and tools are optimized for what must happen next. This is great for focusing on shipping product. After shipping, the usefulness of the documents and tools seem to crumble. They are not maintained anymore, become obsolete and outdated. It’s now difficult to recall questions that were asked and answered in 1993.

I feel that projects need scribes or archivists that track key decisions in a structured way. Their system would track key decisions and the reasons behind them. I want this system to be easily searchable to find decisions made years ago. I also want this system to be readable as prose in chronological order like a history novel. I want entries to be taggable and relatable, for example to highlight that a decision from 1997 was made obsolete by a newer decision from 2004.

I haven’t found tool support for this idea. Maybe it’s been tried and discarded but nobody kept records.

Keeping track of key decisions

Is documentation going the way of testing?

Documentation that is closer to code is more likely to be read and updated. Information in a wiki or shared documents in the cloud go out of sync with code very fast. The effort and diligence required to keep them in sync is an intense job most programmers are unwilling to do.

The obvious conclusion is to tie documentation very closely to code. However, this does not help. Programmers seem to have a kind of comment blindness. Even existing comments that specifically answer the programmer’s questions are often subconsciously ignored. And that’s just the reading part and doesn’t touch on the problem of updating comments. It doesn’t help that many IDEs visually de-emphasize comments over code.

This reminds me of code testing. In the beginning, programmers wrote code. As code became more complex they realized how hard it became to make changes without breaking something. Many programmers started to adopt testing frameworks to quickly learn about new defects in changed code. However, code and tests quickly went out of sync and test coverage decreased over time. Code coverage tools were created and and some companies these days require minimum coverage percentages for changed code to make sure tests stay in sync with code. Many companies have dedicated test engineers who handle that.

Can the same be done with documentation? What if you made a change to a commented line and some part of the toolchain explicitly asked you afterwards if the old comment still applied? Make a change to a method and the toolchain asks if the method documentation is still appropriate. Same for classes, packages, and whole programs. Whenever you make a change, you have to confirm that the existing comments and documentation on the same abstraction level still apply.

Will we see companies with dedicated comment/documentation engineers?

Is documentation going the way of testing?

Syntax errors don’t matter on the whiteboard; but they kinda do

The common wisdom is that syntax errors don’t matter when you’re up on the whiteboard for a programming interview. Who cares about unbalanced parentheses or a missing semicolon? Who cares if you forget a cast before passing a value to a standard function? The common wisdom is wrong.

I used to tell candidates not to worry about syntax mistakes. I did that until I had interviewed so many candidates that I realized that maybe 5% of them write whiteboard code without making syntax errors. The astuteness and precision of these candidates is inspiring. All things equal, if you make syntax errors on the whiteboard, you’re already behind.

I noticed a second issue when writing up interview feedback. When I transcribe whiteboard code, tiny errors like a missing semicolon turn into comparatively large problem descriptions like “// missing semicolon”. That’s 20 characters of problem description for a one-character error. I have to jot that down so feedback reviewers don’t think I made that mistake during my transcription. On the other hand, if the candidate only finds the naive solution instead of the dynamic programming solution I need just one sentence for that. That’s maybe 500 characters of candidate weakness summarized in 100 characters of feedback; a problem to description multiplier of 0.2 instead of 20 for the missing semicolon.

Of course, only finding the naive solution to a problem is a much bigger issue than a missing semicolon but how do feedback reviewers subconsciously process that? Do they think of the missing semicolon as a much bigger issue because the problem description takes up comparatively much space?

I now tell candidates that syntax is not the most important thing but they should still try to get it right.

Syntax errors don’t matter on the whiteboard; but they kinda do

Ambition as an asymptote to goals

Is someone’s ambition an asymptote to their goals? Here’s what I mean: Is someone’s ambition trajectory bigger when they’re far away from their goals but diminishing the closer they get to them? This occurred to me talking to someone else that shared this experience. We agreed that we both are close to what we had longed for ten years ago. Now that we’re nearly there, what to aim for next?

The general consensus seems to be that people get less ambitious as they get older. Let’s assume that’s true. Is that because people settle after they realize their goals are not attainable? Or is it because they are closer to their goals from, say, ten years ago and – due to the law of diminishing returns – are not willing or able to completely achieve their goals without a disproportionate effort.

If ambition is asymptotic to goals, do people that start out with loftier goals have an inherent achievement advantage over people with modest goals, just because their ambition asymptote is accelerating for a longer time before slowing down? People with modest goals usually come close to achieving them fairly quickly. Does ambition just fizzle out at that point because you’re done?

Can people reset their goals and avoid falling into a slump? Obviously it’s possible. There are many stories of people who did something for decades only to quit their old lives and do something completely different. Still, just getting your ambition trajectory back from deceleration to acceleration seems like a tremendous undertaking. Can we plan ahead to avoid that? Can ambition be turned from an asymptote into something that doesn’t decrease the closer you get to your goals.

Ambition as an asymptote to goals

Tracking things to avoid mental downtime

Do you know that feeling when there’s just nothing to do at work? That exact moment when you drift off into your thoughts and browse your favorite website? I vaguely remember it. It was a familiar feeling at previous jobs. I don’t experience it a lot anymore. I don’t think that changed only because my current job is busier than those I had before. I think I actively learned to avoid it.

What happened is that I became better at tracking things. It’s not so much that I have more work to do. In the past I just forgot the things that needed to be done. That’s an unfortunate situation to be in. I was bored at work because I thought there was nothing to do. But there were things to do. I just forgot. First I was bored and then I was angry about forgetting. Great times.

I am still not a good tracker of things. At least I have a to-do list now. It’s my customized inbox. I am in the sweet spot to get through most of it on an average workday. Inbox Zero doesn’t happen a lot. Maybe once or twice a quarter. Inbox Three happens nearly every day. The bug tracker still piles up requests but those don’t count.

Inbox Near-Zero is a mental boost. The small size removes the sense of overwhelming that huge inboxes have. It empowers because it makes the goal visible and seemingly in reach. Even better, when I am done with one task, I know what to work on next. I have completely eliminated the need to mentally recall things that needed doing. Those were the moments when I drifted off to my favorite websites. I opened them and suddenly half an hour had passed. Mental downtime accumulates without you noticing.

Tracking things to avoid mental downtime

Expressive languages and whiteboard coding

If you write Java or C++ code during a whiteboard interview you are probably doing it wrong. There are good reasons to choose Java or C++ for whiteboard interviews. Maybe your interviewer asks you to use one of these languages. Or maybe you know that one weird Boost trick that C++ standard authors hate. If you don’t have a very good reason, stay away.

Time is very precious in interviews. How much time do you usually have? Forty-five minutes? Sixty minutes? How much of that is left after small talk with the interviewer and discussing the problem? Thirty minutes? Maybe thirty-five minutes? Unfortunately, you are really slow handwriting code on a whiteboard. Don’t waste time on a programming language with a lot of syntactical overhead. Tokens per minute matter. Pick a language like Python to write denser code faster.

Donnie Berkholz crunched the data and tried to come up with a metric for the expressiveness of programming languages. Without discussing the validity of this particular metric, I like the idea. For a whiteboard interview please choose a language that’s far to the left side on Donnie’s results diagram.

Now you might say that other things matter more in an interview. Maybe think more before you write code. Yeah, maybe. Maybe whiteboard interviews are a terrible idea to begin. Yeah, maybe. Maybe you have other complaints about the common software engineering interview process. Yeah, maybe. None of these matter when you’re standing in front of a whiteboard, black marker in your hand. These things are also outside the scope of this post. Maybe I’ll cover them in the future. Yeah, maybe.

I see too many candidates who choose to put themselves at a disadvantage by voluntarily using a syntactically heavy language at the whiteboard. Don’t be one of them.

Expressive languages and whiteboard coding