There’s something I’ve been trying to achieve this year. Really, it’s something we all try and achieve, but it’s something I’ve been giving more thought to lately. Efficiency.
That’s dumb though, who tries to not be efficient? Why would you act against your own interests of time? Well, the answer I find is, a lot of us are less efficient than we can be. Specifically today I would talk as a software developer and efficiency in programming.
So let’s set up a scenario. We’ve just hired two new developers who are completely equal in skill. Let’s call them Linda and Tina. We give them similar tasks. Linda gets her task done in a single day, whereas Tina takes two days to finish her task. Who was more efficient? It’s not such a simple answer.
In the pursuit of speed, Linda may have inadvertently been the less efficient of the two. Let’s go over why.
“There Was No Time For Clean Code”
This is an obvious one. Just because you’re faster doesn’t mean you write clean code.
Often a lot of the code reviews I give at work end up being caused by the developer trying to get the task done as quickly as possible. Sometimes this is valid, sometimes you do really need to just get it out as soon as possible, but at what cost?
Common issues are blocks of code that have been copied all over the place, or hard-coding values in place when it’s better to have done it programmatically. Sometimes it’s just variable names that make no sense or dumping your code inside existing code without stopping to do minor refactors.
Again, this can be valid sometimes. Sometimes you do not have the time to write good code, but instead ship whatever is working. It does make a lot of people happy too even if there aren’t strict deadlines. You have happy managers for meeting targets ahead of schedule and it makes the developer look good.
That is, till it comes time to make changes later on. An edge case has come up, that could have been caught if your code wasn’t using hardcoded values everywhere. You go into your old code and you can’t understand what your variables mean. You change one block of code and forget you have to change it in 5 other places that you copied it around to.
This is where I think code review really helps.
It forces the developer to slow down to be vetted and to have their code on display, and it forces them to reason about their design choices. This means they’re more likely to keep their code tidy for fear of being called out for it and having to explain it. It means they get an outsiders perspective on their design, and it forces them to take a step back and see the forest for the trees. All too often we get lost in the code itself and forget how it all relates together.
This is not to say that you should leave your developers in fear of code reviews, but it’s indeed a scary process for new developers (and some veteran devs). It’s putting your hard work on display and asking to be torn apart.
I think a successful code review process can be constructive, critical, and more importantly teach the developers to be better. It changes from dreading the process to looking forward to it because you take pride in your work, and want it to be as good as possible.
It also is the place I see my favorite excuse…
“It’s Just Throw Away Code”
This is my pet peeve. Seriously. Don’t put code into production and then claim it was throwaway code when I ask you about it.
This is something people who want to be fast always hide behind. “I’ll just change it later when I get time”
Firstly, You won’t get time. Write it well the first time or we’ll be paying the price later on.
Secondly, why would you double your own work? Why would you write code that you now have to maintain if you’re just going to rewrite it again. You should never be aiming to rewrite your code while you’re writing it to begin with. That’s just daft.
Yes, you should have reasonable layers of abstraction so that you can rewrite it if you need to, but that’s different. That’s good API design, whereas hiding behind ‘throwaway code’ is just being lazy.
Speaking of API design, it is something that I think more developers should be taught because I often hear this…
Sometimes it’s good to just take a step back from the code and look at it in context.
“This Will Only Be Used By My GUI (or my library)”
A lot of the code review comments I give on user interfaces is that they need to decouple their logic from their interface. The most common response is that it won’t ever be used outside their user interface.
The problem is, if someone finds your tool or application useful, they will want to leverage it and often that means your pretty interface won’t be part of it. So now you have to spend all this time refactoring your code to decouple it from the user interface.
Properly decoupling a GUI and the underlying logic does require some time and thought to do cleanly. It’s not as trivial as it sounds and it requires the developer to put on their software architect hat and architect their design rather than focus on pushing out a feature.
Again though, this is something that a little extra time before hand could have saved you in the long run. Making sure your code can be used without any interface, or indeed, making sure your code can be called as a library for other projects is the hallmark of efficient development.
The alternative is making a new library or re-implementing your logic for every project. At the very least it requires at least one rewrite of something you could have done from the get go.
Designing your code like an API isn’t easy though and you really do have to think about other people. It requires a lot of care and it goes hand in hand with my next point…
“I Don’t Have Time To Write Documentation”
This is a huge fallacy. You always have time to write documentation, but I think it comes down to people thinking of documentation as needing to be this giant, in depth bible of the code. Of course, the more in depth you can go the better, but all you really need at a minimum is to add a docstring to your functions and write a ReadMe.
How does this make you efficient though? Well the amount of time you have to spend explaining your code to people and helping them with issues, could easily be spent writing documentation instead.
Seriously, if all you did was write a README.MD file with some usage examples, you would be miles ahead of so many repos online. That’s enough for a lot of libraries to be picked up by people and used. They can figure out quite a bit from just a few example snippets and it cuts down on how many questions you get asked.
Don’t stop there though. Document your functions. Add docstrings, explain your parameters and put comments in your code. That will dramatically cut the amount of time you have to spend explaining your code to someone else.
More importantly it will cut the time you need to spend re-familiarizing yourself with your own code when you eventually need to get back into it. All that time spent going, “I wonder how this worked…”, could be cut completely because you read your thought process from when you wrote it.
It doesn’t even take that much effort. IDE’s like PyCharm will quickly fill out your docstrings for you. Plus you get advantages like basically having a lot of your documentation done by just doing that. Tools like Sphinx can simply extract your docstrings and make documentation out of it.
Time spent now is lots of time saved later. Not just for you, but everyone using your code. Those people may even be inclined to help you maintain your code, but I often see this one..
Documentation doesn’t need to be a massive bible. It can be as simple as a Readme, docstrings and comments.
“Writing Tests is Hard”
Well you know what is hard too? Having your code do the wrong thing in production, wasting lots of man hours and having to answer to your manager how this happened. Write Tests.
Ideally you’d have as much coverage as possible in your tests, but even a few tests can dramatically cut the error rate of new commits to your code. This in turn can make it easier for people to contribute to your code because you’re not spending as much time vetting their code, and they’re not as afraid of breaking something important.
“It’s Critical and Needs To Be Done Now”
This is completely valid. Sometimes you don’t have time to be meticulous. Sometimes you just need to get it now and have a task list piling up that needs to be addressed right away. That’s the reality of the world of a developer and sometimes you can’t escape it.
I definitely am not writing perfectly clean code that can be reused. I too often forget to document my code and I’ve only recently started embracing tests in my code. That said, I think it’s important to try and aim to be efficient, because that task list that’s piling up will only keep piling up otherwise. If 10 minutes spent here can save me 30 minutes tomorrow, then that’s definitely worth being a little slower. If a whole day can save me a week of time over the course of a year, that’s time well spent.
So write cleaner code, write documentation, write tests and make everyone’s lives easier. If you’re a manager, encourage your developers to spend time to do it right and give them that liberty.
Always try and be as efficient as you can be, even if that means you’re not the fastest. You’ll be the turtle in this race and come out ahead.
As always, here’s a relevant XKCD (https://xkcd.com/1205/)