My Code Quality Challenge

I have an honest question for you:

“How good is your code?”

It’s a hard question to answer, even for somebody like myself that has been writing code for 20 years or so. There’s a lot of nuance into what makes ‘good code’ and as your career progresses you’ll find that a lot of it comes from a personal perspective as well.

With that in mind, this past January I took part in something that I found surprisingly enlightening, Ben Orenstein’s Code Quality Challenge. It was delivered via a daily email with each day having a new challenge for you to attempt to achieve with your daily codebase(s). The idea was that you’d spend at least 20 minutes each morning working on the day’s challenge, which would range from tooling and knowledge updates to changes to how you actually write your code.

To summarize, I found it surprisingly difficult, even if at first glance the individual challenges seem simple enough. With large, years-old repos there’s a surprising amount of things that can be made better beyond the stuff that you probably fight with every day while doing your job.

Here’s a quick summary of my favourite exercises from the challenge, if you want to explore the rest, unfortunately, there isn’t another cohort of the email delivery planned, but the exercises are on display in the forums.

Update your README

I had thought our app’s README was pretty good, but we were actually missing a few key items:
* Where to ask questions
* Who to get to review PRs
* Where to look at the output of our CI pipeline

Trim the branches / Tidy your open PRs/issues

These were two separate tips, but they’re similar enough that I feel they can be combined easily-enough.

I was surprised by how many branches that were sitting around for PRs that had been merged/closed, or simply were too old to ever consider merging (2 years). If you’re using a tool like Github it’s easy to see which branches are lingering on your master branch (on origin) but the tip itself also offers lots of techniques for cleaning up for your local copies of repos as well.

Extract a compound conditional

The article explains it better than I can do here without blatantly plagiarizing the thing. Even with code that I thought was pretty simple to understand, once I started implementing this concept I noticed code immediately started to read more clearly than it used to. Sometimes it’s the simplest ideas that have the biggest impact 🙂

Nuke TODO comments

I have to admit, this one hurt…

The title says it all, grep your codebase for TODO/FIXME etc. and either fix them then and there, remove the TODO comment, or ensure that it’s actually tracked in whatever work-for-future-you system your organization is using. I pulled the plug on this one at 20 minutes with still 400 comments left to review, but I did set a reminder to revisit the results each week.

Create a bin/setup script

What if instead of all those instructions to get started in your README, you simply had a script that did the majority of the work for you? That’s what this challenge suggests, and it’s highly worth exploring if it works for your project.

Want to try for yourself?

Unfortunately, Ben has at this time decided to not run another cohort of the challenge for the time being. I’m secretly hoping that it’ll come back in the future so that I can send all my coworkers here and unleash these learnings across all our repos.

If that doesn’t happen, the list of exercises is currently available here. Maybe set a weekday reminder for yourself to take a look through a new topic every day? I promise you’ll learn something, and your code couldn’t possibly end up in a worse state after completing even some of these challenges.

What did you think of the challenges? Do you have challenge ideas of your own? What do you do to make sure your repos are in top shape? Let me know in the comments.

The Value of Getting your Hands Dirty

As software developers we spend an inordinate amount of time both indoors and staring at glowing panes of glass while sitting firmly on our butts.

Today I’m here to tell you to get off your ass!

I’ve never been afraid of getting outside or digging in to some physical work. Though often in talking to people when I mention a recent home-improvement project I’ve been working on they respond “oh, I couldn’t do that!”.

You want to know the secret?

When I started doing many of my own home projects, I didn’t know what I was doing either!

With all this technology at our fingertips, it’s incredibly easy to lose the pride and sense of accomplishment that comes from physical work. In my experience the benefits are numerous, but here’s a few nuggets that come to mind:

  • working with your hands without a keyboard
  • though you’re still solving problems but you’ll feel like you’re using a different part of your brain
  • you can create something in the real world, exactly the opposite of the virtual products create
  • it’s great for clearing your head from challenges you’re having in your technical work
  • sore muscles at the end of the day FEEL GOOD!
  • you just might get to spend more time outside!
  • there’s a whole new set of skills out there that you couldn’t even imagine
  • you’ll save money on small projects or fixes vs. hiring somebody

After you’ve done a few smaller things, say rewiring an outlet or fixing a leaky pipe, you’ll quickly grow more confident in your abilities. You’ll quite likely find yourself taking on larger projects, it can be an addictive and empowering feeling. For example, in two weeks I’m going to be ripping the siding off one side of my house, building and pouring a concrete slab and then extending my roof to build a new shed. A far cry from the drywall repairs and light switch replacements that were about the limits of my abilities few years ago.

So get out there, get your hands dirty, and do some work that doesn’t involve a computer. I promise you will feel a different level of accomplishment than what you’re used to in your day-to-day work.

I just shipped a single-page application without any frameworks and I feel fine

This past week I built a tool for a freelance client’s website that allows their visitors to find the nearest dealer for their products.

The previous version of this tool was written in Classic ASP (which I also maintained) and pulled its data from an MS Excel spreadsheet. Yes, you read that right, an Excel spreadsheet was the backend data repository for a live website in 2016. I suspect this approach is still out there more than us modern web developers would care to admit.

Anyway, my first job was to move the Excel data out to a real database, MySQL in this case simply because that’s what the web host supported. It ended up being pretty easy thanks to Excel’s ability to export to CSV.

Next, I built out a basic search class for sending queries to the database. I needed to be able to filter the data by any permutations of the available fields (think business name, city, province, etc.). A few simple 5–10 line functions later and it was done.

The API was even easier, I just checked $_GET for my trigger argument and called the associated function in my new search class, returning the result as a JSON payload. This made implementing the client JavaScript super simple.

Other than jQuery (simply for the XHR abstraction) the client-side was built with vanilla JavaScript. I had a few functions for drilling down in the filters, for example, if you selected a province I would only show ‘city’ options that were in that province. There was also one for rendering the HTML of search results. None of these were more than 15 lines of code.

I’m quite happy with how it all turned out and so is my client since they understand the code without having to learn some framework. They’re also able to make some changes on their own without having to involve me, which quite honestly I’m ok with.

Don’t get me wrong, I’m not against web frameworks, I find them quite useful when they’re appropriate. I do firmly believe that not all web things are in need of a framework. Next time you’re tackling something small, see what it’s like to write it by hand. You might just surprise yourself with how easy it can be and how simple the result ends up.

Known Unknowns?

Recently I tweeted this:

Afterwards I continued to wonder whether coming away from a tech talk with more questions than I started with was a good thing or not. It can certainly shake your confidence and make you feel like you might not know as much as you thought you did about the topic being discussed. 

On the other hand, perhaps the fact that you have questions reflects the simple fact that the speaker simply has a different perspective from your own. Perhaps if you were to talk about what you were working on they’d have as many questions come up as you did. 

There’s so much available to be known these days in the tech world, especially when it comes to the web I feel. As a result, it’s incredibly easy to get discouraged, or to constantly feel the weight of all the things that you know you don’t know. I know I certainly struggle with this. 

I’m not sure what the answer is, but my strategy is going to be to try to be ok with not knowing everything. Maybe it comes with age and maturity, but it’s obvious to me now that aiming to know everything, no matter the topic, is a fool’s errand.

I’ve always been a great consumer of information. Recently though I’ve been trying to shift my focus towards only needing to know enough to take the next few steps I need on my journey. Once I’ve taken those steps I’ll be able to look from that new position of knowledge and experience and know what needs to be known next to keep going. I feel like this will help with overloading myself with information without really figuring out how to apply any of it.  

After all, who cares what you know if you can’t do anything productive with that knowledge?

What? It’s only been two years…

Scroll down to see this blog’s shame.

It’s been over 2 years since the last time that I’ve posted anything here. Now, that doesn’t mean that I haven’t been writing during that time. In fact, I’ve probably written more in the past 2 years than at most other times in my professional life. I just haven’t been writing as many things that I thought would be a good fit for this site.

That starts to change today.

There’s this odd thing that happens when you write frequently, your brain gets used to thinking of things for you to write about. I’ve been doing quite a bit of writing over the past few months for my stories over at Wattpad (where I work). I’ve also been writing in more of a professional journalling sense, who knows? maybe that’s part of getting older and not trusting my memory as much as I used to.

As a result, I have a lot of drafts sitting on my hard drive for things that it turns out would be a good fit for this space so that’s exactly what I’m going to do with them.

Things will likely be a bit scattered at first, but as I keep going I know the focus will dial in and some sort of theme will emerge.

I do know however that a majority of what I will be talking about pertains to being a modern JavaScript developer. There will probably be the odd piece about being a father (of two awesome boys), being a bit older (35 last I checked) and having been in the web industry for almost 20 years at this point (I published my first web pages in the late 90’s). I’m also open to suggestions for topics from my readers, something that I’ve found immensely valuable with my stories over on Wattpad.

Stay tuned, more coming soon…