Write that down!

This is a guest blog post from John Obelenus. Enjoy.

Dear new developer,

Even when I was a kid in school I hardly wrote things down. That’s why we had textbooks after all! I was baffled by other students in college furiously transcribing every word that came out of the professor’s mouth. Now I have a career in the world of software where we track everything. Git holds all the code commits, email is never really deleted, and project management and issue tracking tools keep track of what we’re doing and have done. How could anything go missing?

I constantly looking for things and cannot find them. I get a bug report, look at the code and say to myself “That is obviously wrong, let’s fix it.” I look at the offending commit that introduced the bug (of course it was me). But what is not there? The reason for the change. So I look at the project management tool we use. And someone definitely asked for a change, but, I’m still not sure why. So I search through my email for the few days before I made the change, and…nothing. I still cannot really figure out why we all decided to make a change which introduced a bug.

Or, worse yet, someone asks for a change. All well and good. Then a month later, someone asks to change it back. So you shake your head and make the change. Then someone is confused why this is happening, and calls a meeting and invites you to help figure it out. What are you going to bring to this meeting? Did you write anything down? I never used to. Now I do.

Now I have a notepad next to my laptop. And I have a notebook on the shelf. I make better use of git messages and write down who asked for changes. When working on a feature, or a bug, and find something…“interesting” I make a Github wiki entry explaining it. I write a comment in the code base explaining it. There are two kinds of documentation — useful documentation, and redundant documentation.

No doubt many people have told you to comment your code. I hope many people have told you never to comment a loop with // loop over the array. That is not increasing clarity, its just duplicating what the code is doing. Adding noise, not signal. My contention is that comments are rarely useful for explaining “What this code does…” but rather, explains “Because of X, we are going to do…”.

Future you is going to be very happy if you start documenting the intent behind what you’re doing. Good code is easy to read. Bad code is capable of being understood with time. But code doesn’t tell you why you’re doing all this work in the first place. Maybe something has changed and you don’t even need this code anymore — deleting code is the most satisfying feeling. But you won’t know unless you know the intent, the purpose, of the code. And the rest of the folks you’re working with are going to be very happy as well.

If you write everything down (and make it public), they won’t need to tap you on the shoulder when you’re in “The Zone” to ask. When someone wants to set a meeting to understand why things are “The Way They Are” you already captured that information. You can send them the link and kill the meeting (Ok, maybe killing meetings is more satisfying than killing code).

We only have so much time in our life, and we already work long hours. Let’s make future us happier by writing things down, so we don’t have to figure it all out again. We figured it out once when we wrote the code. So capture the knowledge in that moment in time. And Write It Down!

Sincerely,

John Obelenus

(Previously published at Medium)

John Obelenus solves problems and saves time through software and crushing entropy

 

J

Be a Just in Time Learner, part I

Dear new developer,

There’s the concept of a JIT compiler. I was first introduced to it with the HotSpot Java compiler. The idea is that a compiler can look at code and find the code that executes often and optimize it, sometimes compiling it down to faster code, sometimes unrolling loops. I’m no compiler expert or even intermediate, but the results speak for themselves. JIT has spread elsewhere (python, ruby, javascript).

As a new developer, you should be a just in time learner. Just like the compiler watches to see what is used often and then optimizes the code that runs fast and often, you should do the same. That’s why I recommended you learn version control and a text editor. These are tools that, as a software developer, you spend a lot of time in. So learning them well will save you time in the long run.

But what about the intricacies of a language or framework. That’s important too. But it depends on how often you predict the issue will come up.

Here’s a great chart from XKCD.

If you spend two hours remembering how to do something but you only do it yearly, and you learn it well enough to do it in one hour, you save five hours over five years. Does this make a lot of sense?

So, basically, I’m saying optimize for the things you do often. Another way you can do that is to make what you learn do double duty:

  • When you learn SQL you learn a way to query across multiple different databases.
  • When you learn javascript, you are learning a language that you can use on the front end (in the browser) and the back end (on the server).
  • When you learn vi keystrokes, you can use them to edit a text file in a terminal on any unix machine, on the command line to navigate your history and directory structures, and in eclipse or visual studio.

Sincerely,

Dan

Making mistakes is OK

Dear new developer,

One time, not too many years ago, I was using git. I had used it for some personal projects, but hadn’t used it in the team setting before. We were using this git branching model. I was creating feature branches and working on them.

However, often I would be working on the same feature branch as a colleague. The first couple of times I was doing that, I used ‘git checkout -b <branchname>’ to checkout the branch. I’d then pull down the remote branch ‘git pull origin <branchname>’ and work on it.

Do not do this. Doing this will checkout a branch named <branchname> but it will be off whatever branch you were previously on. The pull will then merge the remote code. So you’ll get the code you want to work on, but there will be other code lurking. No good!

Instead, run ‘git fetch origin<branchname>’ and then ‘git checkout <branchname>’.

I point this out not because I’m trying to teach you version control (though you should learn it).

I point it out because this was a mistake. I don’t think any code escaped into production, but it definitely confused some team members and could have been very bad. It’s one of many many mistakes I’ve made in my career.

Mistakes happen to everyone. It’s important to learn how to handle them.

First, find out what the mistake was. You need to have an understanding of the mistake so you can avoid repeating it. This may be a conversation with another team member, research, or both.

Second, acknowledge that you made the mistake. If you work in an environment where you cannot acknowledge errors, make plans to leave as soon as possible. You don’t have to wail and beat yourself up, but just saying “oh, wow, I really screwed up that git branch stuff. Sorry!” is going to let people know that you made a mistake and that you are adult enough to know it.

Third, clean up your mistake. You may need some help doing so, but part of taking responsibility for your mistakes is fixing them as best as you can.

Fourth, avoid making the same mistake again. This may involve keeping a notebook, a writing a blog post, or just committing the correct solution to memory (this depends on the scale of the mistake). Bonus points if you do this in such a way that other folks, either internal (wiki page, slack message) or external (blog post, stack overflow question and answer) can benefit from your mistake.

Mistakes happen. It’s OK. Don’t pretend you don’t make mistakes, own up to them, and try to make new ones rather than repeating.

Sincerely,

Dan

Learn Version Control

Dear new developer,

If in doubt, put it under version control.

Version control is a way for you to keep track of the core nuts and bolts of code, which are files on the filesystem. Version control lets you make mistakes, err experiments, and roll back time to when things worked. Version control lets you see who made what changes when to which files, so that when you need to find out who to ask about the bizarre function in class XYZ, you can.

Don’t be surprised if that person is you.

There are many systems of version control. What you use depends on your needs, the most important of which is how many people are interacting with your system. But something, even a crufty old system, is far better than nothing.

There are plenty of free version control systems out there, so if you aren’t using something, set up one of the free ones (or better yet, use a hosted service) and give it a try. Github, bitbucket, gitlab, all are happy to walk you through how to store your code in their system. Learning one of the modern version control systems will help you integrate into any team, because running a software project of any size without version control is a foolhardy endeavor that only is typically tried once.

There are some items that don’t belong in version control. Large binary files belong on a storage system like S3. Secret information, like a password, is better kept out of version control and in a secrets manager or environment variables. Documents that are going to be edited by nontechnical users should probably use a shared document repository (which will likely have versioning built in, but hidden).

But everything else, all the source code and build scripts, all the infrastructure setup and documentation, all the assets and sql scripts, those should be kept in version control.

Sincerely,

Dan