The Best Code is the Code you don’t write

Earlier in my software development career, I would get an assignment and eagerly jump into writing the code.  Hours later — after frustration and then the joys of success — I had the code done.

Writing the code was a learning experience for me — I got better at programming the more I practiced — and this was all ok.

Sometimes, the client was super happy and the task was done.   The computer did what it was supposed to do.  Assignment completed.  Yay!  I felt like a genius.

Other times, it turned out that my interpretation of the requirements was not the same interpretation that the client had in mind, or the business requirements had changed in the meantime, or for some other reason, the outcome was no longer the desired one.  So, I’d have to revise the code, change it to meet our new shared understanding of what we need to accomplish.

As a programmer who is learning, having to go back and write more code, is not necessarily bad.  It means more experience.  But, from a business perspective, this means wasted money, wasted time, and a longer route to getting to “done.”

At a certain level of expertise in any given programming domain, there is no longer a question of whether something can be done, but whether it is the right thing to do.

The vast majority of client requests are completely feasible.  It might take 2 hours or 30 hours, but a programming solution is possible.  There’s very few tasks that are “impossible.”  It’s more a matter of whether it makes business sense to spend the time on the task, when there may be other items that would derive more business value.

Since I work at an agency, I use the term “client”, but this applies to any programming endeavor.  Just because you can think up the programming solution, doesn’t mean it would be the best use of your time to implement it.

I love designing software systems.  In my mind, I can solve any problem.  But, I now do not actually write out the code until I am sure of the value it is going to provide.

“Value” can mean a lot of different things.

If you’re working for a client, it’s most often business value — maybe the code is going to provide a proof of concept, maybe it’s going to bring in additional revenue, or maybe it’s going to automate something.  In these cases, your job as a software developer is to ask the questions to make sure you understand the value you are delivering.  Don’t write the code first.  Instead, read and ask a lot of questions.  You will hopefully spend less hours programming the wrong solution.

There are times when the “value” is the learning experience.  Which is 1000% awesome.  But, don’t mistake that kind of value from business value.

But, if the code isn’t teaching you something, or isn’t generating money, I’d ask, why are you writing it?

So step back, imagine the systems in your head, and ask questions.  As a skilled WordPress plugin developer, I once imagined a whole plugin…. and I enjoyed thinking about the software I could build… But then I realized that it was completely unnecessary.  So I didn’t write it.

Just because you can, doesn’t mean you should.

Is the bug in the code or the data?

The answer is always in the code.  Or is it?

Yes.  And no.

The code depends on the data being a certain way.  If the data is different, the code will fail.

This is the lesson that I learn (again) after an almost perfect experience of writing a test-driven solution.

I say “perfect” in that, test driven development is sold as a better way to program.  In an ideal world, it’s a better way to develop because you write the tests first, which saves you time because the code works the first time.  It’s the programmer’s equivalent of the construction worker’s statement “Measure twice. Cut once.”

Figure out the specifications first, before you write any code.  You can’t write good tests for uncertain specifications, so the very act of writing the tests will lead you to find out the right information.  This, in the end, should make it easy for you to build software that works the first time.

The time saving promise of writing unit tests is that they will save you from wasting your effort.

Does this pattern seem familiar: Write some code, then realize that you did it wrong, write some more code, then realize that you’re not sure about this other part, wait, go ask some questions, come back, re-read what you’ve written… and maybe write some more (buggy?) code… run some data through your code to see if it works… fix something… test it again… and so forth.

So recently, I wrote some tests, wrote some code that passed the tests, and my code worked the first time, on my local sandbox.  Yay for me!  I did it right, or so I thought.  I then tested it on our development server.  It didn’t work.  What could it be?  I start thinking about the differences between the environments.

It puzzled me for about a half hour.  Then I took a break, participated in my favorite activities, and then had an ah-ha moment.  I realized that the answer to my bug could be in the data.  Sure enough, I returned to my desk and found that the real data was missing an array key that I had assumed would be there.

Lesson learned: Use real data for your unit tests.

How to Solve a Software Bug FAST

[ @todo: Insert photos of bugs and fun stuff.]

It’s not always important to solve bugs with great speed.  In fact, “slow down” is a tip I give myself regularly.  BUT, it’s true that I’ve figured out some favorite techniques that help me solve software development bugs in a timely manner, and I hope you find something helpful here!

#1 Read the bug report carefully and ask questions.

Most initial bug reports don’t have all of the important details.  Ask questions so that you don’t lose time going down the wrong road.  Well thought out questions show that you are working on the issue, which is good news to anyone who cares about it getting fixed.

#2 Reproduce the bug, ideally on your local development sandbox.

You’re going to have to set up the bug locally anyway, in order to test your fix, and my advice is to make reproducing it locally something you do very early on in the debugging process.

The process of trying to reproduce it may shed some light on the situation, which helps with knowing what questions to ask (see point #1).

I have an approximately 2000x greater chance in fixing a bug I can reproduce than in fixing a bug that I can’t reproduce.

#3 Ask for Help

If the importance is on the speed on which the bug gets solved, then the more brains, the better!  How soon you should ask for help probably depends on the seriousness of the issue, and your likelihood of solving the issue on your own.  Be honest, do you have the technical knowledge here?   Have you solved other similar bugs before?

There is no shame in not knowing something.  Often it is just a matter of experience, which you will gain in time.

#4 Watch out for the Wild Guesses

The reason not to ask for help, is that sometimes people will help by giving suggestions that could not possibly be correct.  Be careful!

I only consider answers which “could not possibly be correct” after I’ve already checked out the technically most likely causes.  Don’t go down a rabbit hole that’s a 1 in a million chance.  (On the other hand, don’t assume that you have superior knowledge, and be careful to not dismiss a suggestion just because you don’t understand it.  Ask questions.)

#5 Define the scope

Software systems are HUGE!  Let’s make the haystack smaller…

If this is a website bug, does it still happen with Javascript disabled?  That’s a good way to tell if it’s a backend or frontend issue.

If you disable a plugin/module/theme or otherwise remove some included files, does the bug go away?

Another way to define scope, is to use a debugger and put a break point before and after where the bug exists.  Examine what happens to the relevant variable values until you can be certain of the code block where the error happens.

#6 Assume it’s a recent change.

Did you do something recently?   Look at your recent commits, software updates, etc.  If this is a huge problem that did not exist before, something must have changed to cause it.  You can also check out previous git commits/other git branches and see if the bug existed in them.

#7 Stay Focused; Put the “Emotions” aside.

Has this bug caused your adrenaline to shoot up?

Or, has it caused others to stress?

Try to put all of your feelings aside, and follow a process driven by logic instead.

I find that understanding emotion is very helpful when interacting with people, but computers don’t care how I’m feeling.

YOUR emotions, as well as the emotions of OTHERS can interfere with your ability to use reason to solve an issue that’s logic based.

Do what you need to do in order to stay focused on solving the issue.  I (try to) banish my emotions to the other room.