Introduction
A workmate of mine has recently been dusting off his coding skills and using PowerShell to access REST APIs to pull data and graph it in a dashboard. After falling down the never ending rabbit hole for a while, he tweeted the following question:
is there such a thing as bad code, as long as it does the job and meet the requirements? Discuss …
— Craig Dalrymple (@cragdoo) August 8, 2017
It’s not really a question that is best answered in a series of separate 140 character responses so I thought I’d write a brief post to try and distil my understanding of what good code is. A full time developer could probably tear this apart and flesh it out with all sorts of deep and meaningful computer science principles but I’m going to take the perspective of a coding hobbyist, with my target audience being the very same, looking for a quick answer.
Pictures are nice
Let’s keep this as simple as possible. Code can be functional and code can be readable. You want your code to be both at the same time. Let’s discuss those requirements a bit more.
Functional
Code that is functional, by my definition, is code that does what it is supposed to do and does it well. Bear in mind that I am talking about code that works well here. I am not talking about functional programming, which is a separate paradigm (you can melt your mind here). Some KPIs to bear in mind:
- Works predictably. Expected results occur every time
- As bug free as possible. Good run time error checking and code testing
- Good validation of all user input. Don’t let humans screw up your hard work
- Allows additional functionality to be added with relative ease. You don’t want to have to start from scratch every time
Readable
Code that is readable, by my definition, is code that another person who has a basic or even better, no understanding of your language of choice can browse through it and understand what the code does. It also means you can go back to your code in 6 months time and not ask ‘what the hell was I thinking?’. Some KPIs to bear in mind here:
- Follows the language guidelines e.g. in Python, adheres fairly closely to PEP8, code is ‘Pythonic’
- Is well documented. Good code is self-documenting i.e. the intention is clear in the code itself. Next best thing is well commented code
- Not over documented. By this I mean focus on the guidelines and making your code clean. You shouldn’t need a comment for every single line of code. Try to make the intention speak for itself as much as possible
- Does not have duplicate code, which can make understanding code more difficult as well as being generally inefficient. Learn about functions and classes to help with this
Bringing it all together
To write code that puts you on the right path to Venn diagram overlapage (pronounced o-ver-la-par-jay), you do need to put some effort in though. The key steps are:
- Learn some basic computer science skills. Not talking about getting a degree, but if you know some basic algorithms and understand what people are talking about when they reference loops, conditional branching, OOP, etc. you’ll be in a better place to answer the question ‘how can I write code to solve this problem?’
- Learn how the language of your choice implements those different features. Read the online documentation, buy a book, write some code!
- Collaborate. I’m a bit weak in this area myself as the coding I do is pretty much all specific to my workplace and besides, I have justified imposter syndrome. Work on other people’s code and ask for help on yours. This is a great way to gain experience and also improve productivity
- Set out to maintain functionality and readability before you write a single line of code. It’s better to incorporate both these requirements as you go, rather than trying to retrofit them later
Summary
In this post, I took a high level look at what makes good code. In answer to Craig’s initial question on Twitter, I would say code that isn’t functional and readable is not great code and could always be improved. Make functionality and readability requirements of all the code you write.
This post is aimed predominantly at beginners and hobbyist coders. Got any other advice? Post in the comments.
Till the next time.