The Importance of Modernizing Legacy Code

The term legacy code conjures thoughts of dread in developers everywhere. It’s code that’s perceived (justly or unjustly) to be tightly-coupled, hard to understand, hard to change, and just plain out-dated. It’s an immovable object.

The reality is, legacy code is everywhere, and it isn’t going anywhere. So why not make it better, and make our lives working with it everyday easier?

Continue reading “The Importance of Modernizing Legacy Code”

Truly rapid development of admin apps with json-editor

At work we have a lot of configurable settings in our application. Like a lot. For a long time, nobody tackled the task of properly exposing the management of these settings in a UI because they thought it would be way too much work. The settings have a flat unified structure in the back-end, making them awkward to manage logically as a set of related settings. Building support for a large set of arbitrary data types, different editors for each, custom validation, etc. seemed like a daunting task.

In this blog post, I’m going to show how you can use the json-editor library to build these kinds of complex back-office admin apps really quickly and easily.

Continue reading “Truly rapid development of admin apps with json-editor”

Emacs Keyboard Setup – OSX

Before you get going with Emacs on a Mac, there are a number of keyboard settings that you generally want to tweak to get the most fluid and comfortable experience. This post outlines the keyboard settings changes I’ve made that I find essential.

Note: this is targeted towards OSX users. Not all of this will apply to other systems.

Continue reading “Emacs Keyboard Setup – OSX”

Stackoverflow: Road to 5K

I recently reached 5K reputation on stackoverflow. It’s nothing mind blowing reputation-wise for sure, but it feels like a nice milestone that took some time and effort to reach. Thought I’d write a quick post summarizing my experiences on the site and share some tips & tricks I’ve found helpful along the way.

Continue reading “Stackoverflow: Road to 5K”

Making Sense of Stream Processing – A Must Read

Making Sense of Stream Processing Stumbled on this book this week, and devoured it in an afternoon.

Written by Martin Kleppmann, a distributed systems researcher and former engineer at LinkedIn (where Kafka was born), this book explores the ideas of stream processing and outlines how they can apply broadly to application architectures. It’s a small book in a report format, synthesized from a series of blog posts (linked on Martin’s website).

Continue reading “Making Sense of Stream Processing – A Must Read”

AWS Cloud Best Practices

On a bit of an AWS Whitepaper binge as of late. This post catalogs some of the important highlights and takeaways I’ve had reading through a number of them. Despite the fact that it’s all presented in the context of AWS products and services, there’s a lot of information that I think is generally applicable to any cloud architecture. Reading these are a great way to get familiar with the space as no doubt other cloud providers (Google Cloud, Microsoft Azure, etc.) will have similar offerings now and in the future.

Check out the References section at the bottom of this post. I’ve linked to some specific whitepapers that I found the most interesting/generally applicable.

Continue reading “AWS Cloud Best Practices”

Resources For New Software Development Managers

Most new managers are generally ill-prepared for the job. This can be especially true at smaller companies. Even if you do get some kind of management training, it’s pretty difficult to picture a training program that would cover all the important things you would need to know to be a great software development manager. First, and most importantly, there are the things you need to know just to be a good manager of any kind, no matter what field you’re managing in. Then there’s the considerations specific to software development management.

Continue reading “Resources For New Software Development Managers”

The Value Of Listening to Programming Podcasts

Podcasts are great. You should subscribe and listen to some. They can provide a ton of value for a pretty low time investment.

This probably isn’t the first post out there to tout the value of listening to programming podcasts. And of course, it’s probably not hard to see why they are useful.┬áBut I did want to share some tips & tricks i’ve learned from listening to hundreds of hours of podcasts and what I found most helpful in getting the most out of them.

Continue reading “The Value Of Listening to Programming Podcasts”

Why You Should Review And Comment Your Own Pull Requests

Code reviews are a fairly standard part of the software development process at many companies. And for good reason – they are an excellent opportunity to catch design issues, silly mistakes, misunderstandings, or other general code issues. More eyes on a piece of code means a higher possibility of catching bugs.

Pull requests are commonly used as a vehicle for performing code reviews as it’s a great opportunity in the source code control workflow to perform the review. If you use github, bitbucket or a similar tool, you can generate a pull request with the push of a button. These tools also offer nifty UI diffs of the request compared against the mainline or target branch of where the changes are being merged to, making it very pleasant to read.

While the primary intent of this is for others to review the code, I highly recommend you review your own pull requests too.

Why, you may ask would you review your own code? After all, you wrote it. You already know what it does and how it works. And further, aren’t you totally biased and unable to objectively judge your own work?

Conversely, you may be thinking: “of course I double-check on my own work!, this goes without saying”. But there are various ways to go about doing that, and I think this one is particularly effective.

This subject has been written about elsewhere, but the posts i’ve come across have mainly focused on some of the obvious benefits like catching mistakes such as unintended commits, or commented out code. Of course these reasons alone should be enough to get you to review your own PR’s. But there are some more compelling reasons.

Here are a few of the key points & reasoning around why you should review your own PR’s:

Reviewing your code at least one day after completion

This does provide some amount of objectivity as you will have moved onto other things, changed your train of thought, context-switched a few times, etc.

Just like writing an important email, you might draft it the day before, have someone else read it over, but then read it over yourself one last time before you send it to catch any grammatical errors, adjust tone, make tweaks, etc. We’ve all heard the sage advice of never sending an email when you’re angry. You always want to approach it with a cool head, detached from the situation, so that you have a more balanced response. I think the same idea applies to code. Distancing yourself from the original thinking you had while writing the code can help you be somewhat more objective in reviewing it.

Comment Your PR

This is huge. I cannot understate how important this can be. I can’t count the number of times I started writing a comment for a part of a PR I generated and as I was typing it, I found an error or improvement that could be made which was directly related to the comment. It’s kind of like speaking out loud while problem solving in a way, or teaching someone else something you just learned – a piece of code you wrote can really sink in when you are trying to explain how it works to someone else. This can often lead to mental clarity that was not attainable when you were in the weeds while actally coding it.

If you follow the advice from the first point and review your PR at least one day later, commenting the PR can jog your memory and force you to explain what your changes accomplish and how they work. This can often uncover faulty logic mistakes.

Equally as important, is helping your reviewers understand your code. The more your reviewers understand what your code is supposed to do, the better they can assess whether it actually accomplishes the goal, or whether it can be improved. You should help facilitate this as much possible.

Now, you may argue that well-written code should be self-documenting, and I would very much agree. But a PR is a little more nuanced than a just a piece of code. It is more frequently a diff between the current code and your changes. As such, it can be very helpful to indicate why a change is being made, and potentially how it is correlated with another change within the PR.

Be your own worst critic

This is a good thing in code reviews. You often catch things that were very deep and someone else may be unlikely to catch. Remember, other reviewers are only human; they may not look over everything with a fine tooth comb. Let’s be honest, we’ve all glossed over someone else’s PR at one time or another. We’re all busy, and may have lots of other PR’s to go through. Which actually leads to the next point..

You may realize your PR is too big

Big PR’s can lead to the problems mentioned in the previous point. As a reviewer, it’s natural to have a tendency to gloss over a BEHEMOTH PR and just try to find the main points of interest. Help your reviewers be able to be more detail-oriented by keeping the PR’s a manageable size and break them up into several logical PR’s when they get too big.

One approach I’ve used with success in combating this problem is creating a PR with no assigned reviewers (this is possible in bitbucket, not sure about others) and no intention to merge it. This might seem odd, but the idea is that you can make a large change fearlessly, then go back through it in a PR, dissecting the essence of the changes and trying to distill them into separate and coherent PR’s. It’s an exploratory process intended to help you identify an incremental approach to your change, which may just not have been apparent until you got into the weeds. This can work really well on seemingly intractable re-factors.

Conclusion

Be kind to your reviewers and comment your PR’s. Help them help you find the errors or issues in your code by drawing attention to key areas, or make clarifications, etc. Help yourself learn and assess the work you did after the fact, in order to get better insight into what your change is about and how it might be able to be improved.