What is a good code, and why is it all about others, not ourselves?
Software engineers write a lot of code, but you will quickly learn it is often poor quality if you know how to recognise it. There are different reasons for that. From not having enough time to do things properly in feature-obsessed companies to bad habits learnt in past roles and on laziness and not giving a f*** ending.
What is a good code?
So let’s review the main aspects of good code. Since I mostly write in JavaScript, all examples will be based on this language, but they are easily translatable to practically anything else (with little caveats).
Naming convention
We can recognise good code if naming is consistent and styles are not randomly mixed. It helps to fight confusion on the most basic level.
- camelCase — variable and methods naming
- PascalCase — for classes, components and imports as they all behave similarly to classes (singletons, to be more specific).
- SNAKE_CASE — for constants. It depends greatly on a person’s writing style as people often follow camelCase for let and const.
TIP: The let-first approach assumes anything can be re-assigned as default feels nicer and creates a distinctive difference between let and const. Constants are a conscious decision as the SNAKE_CASE stands out as “important” and “can’t be changed”.
Readable names for variables and methods
Variables and function names should be easy to remember. The rule of thumb is that they shouldn’t consist of more than 4 words as they will become hard to follow. Naming is probably THE ONLY hard thing in coding where we spend too much time and still get it wrong. How accurate and self-explanatory names are, says a lot about the person who wrote the code.
/* BAD */
let n = 'No Title'; //you have no idea what 'n' means.let cbo = 'Chief Banana Officer'; //acronyms are usually a bad idealet mojeDane = 'Some data'; //use names in English!function toggle(){} //what the hell I'm toggling? Although, this might be OK as a method in a class as it will be within a context.function togglePopupAndRefreshWindowTrack () {} //try to remember that! Not only it's long, but it also describes what function does.
Efficent functions (DRY)
Functions ideally are doing only one job without changing the inputs (pure functions). All the code and branches should be testable, fast, and easy to update. Re-usability is what we often look for as a sign of a well written code. That also extends to the writing style like functional vs object-oriented, and if you see a mix of both, it likely won’t be good code.
Well structured & styled
The structure is how code is organised in files — by responsibility or purpose. A good code should have a logical flow. You should be able to recognise a few blocks, and each is responsible for doing a particular thing (organised by responsibility), or it starts from defining configuration and variables to private methods and with public methods at the end (organised by purpose).
Styling includes things like consistent indentation, style, and line breaks. All these tiny things matter. How someone format their code will be a good insight into how they think. Attention to detail is what makes good engineers great. These days most of them should be handled by IDE and build tools.
Easy to understand
Easy-to-understand code is a collection of many things. It includes naming, structure and formatting. If all the common sense rules have been applied and code has been written for humans, then it will be easy to read and understand.
TIP: Writing code is like speaking another language. There is scientific proof that it’s not math but linguistic skills that matter most in writing good code. Js, Python, C, Java… are just foreign languages created for humans to communicate with machines. If you are the only one understanding WTF your code is doing, then you failed as a software engineer.
The best code is simple code — always. Using fancy methods, unexpected approaches, and sweet one-liners often results in horrible outcomes — slow and unreadable to anybody. In the end, you always write code for other humans (occasionally for a machine when you have to geek out on performance), and one of the most important signs of good code is how easy it is to read.
// Sweet one-liner but good luck trying to figure out what it does.
// Plus, it is not performant code.
function doCoolThings(n){
return (n).toString(2).split('').reverse().map((v,i)=>v==="1" && Math.pow(2,i)).filter(Boolean);
}// Does the same thing as above, but ultra-fast (2.4M ops/sec)
// Even junior can understand what is happening here
function doCoolThings(value) {
var returnArray = [];
var highestValue = Math.pow(2, Math.floor(Math.log(value) / Math.log(2)));
while (value > 0) {
if (value >= highestValue) {
returnArray.push(highestValue);
value-=highestValue;
}
highestValue/=2;
}
return returnArray;
}
Testable & Tested
Good code is the one that comes with tests and not just dummy line coverage but actually good unit tests. That also includes “destructive” scenarios, which check for graceful failure handling. Even better if tests are backed by mutation tests.
TIP: Mutation tests — if you haven’t heard about that, explore Stryker. This little test suite that will break your code on purpose to test the quality of your tests.
Well commented
Confusing things should be explained, and methods adequately described. The total lack of comments is terrible. On the other hand, too many comments are bad too. Good code has the right balance, and comments explain primarily WHY, sometimes WHAT, and never HO
TIP: If someone says their code is so clean, self-explanatory and doesn’t need any comments, they might be a dick.
Documentation
Code supported by documentation is mainly relevant to libraries and more significant solutions as, very often, you wouldn’t be able to start the project without it. That’s why jQuery gained popularity in the previous decade and dominated JavaScript — their documentation was much better than anything. Easy of use & good docs drove the internet’s adoption rate to over 70%.
TIP: When you write code in your team and follow standards like JSDoc, you have all the tools in place to generate your documentation automatically, without the overhead of managing it in some 3rd party tool. Code comments and documentation solved in one go!
Logical folder structure
It is a bit outside the code itself, but it is essential to have a solid folder structure where the code lives. Files should be appropriately named and consistent between different folders in the naming convention. That also means not ending up with folders that contain everything.
EXAMPLE: /tests folder which contains 100 files with tests for each feature and component that live in another 100 different folders. That’s a poor design leading to future problems (especially when the team grows quickly).
Performance
Code should be fast, and there is no excuse for making it slow. Although, most of the time, it is due to lack of knowledge or simply laziness, often explained with “that’s how I have always done it and was fine”. Of course, how performant code should depend on how often it will be used throughout the app, but making things faster usually results in a cleaner and more readable application. So it’s a win-win situation.
// Both examples are easy to read.
// So why would you use the slower one?// SLOW
// You can use for object and array
for (let item in items) {
console.log('got item', items[item]);
}// FAST
// Only for arrays. For objects, you might go with Object.keys loop.
for (let i = 0; i < arr.length; i ++) {
console.log('got item', items[i]);
}
Implementation examples
Can we see implementation examples? Do we have actual code examples of rendering the particular object, feature, component, or functionality? This applies mainly to libraries but is also very important regarding reusable components and design systems. The easiest way to start with something and see how it works is by seeing them in action with an easy copy/paste of the code. It’s part of good documentation and answers another point from this list…
Is it a right solution? Does it work?
If the code looks like someone used a hammer because they saw a nail, that’s probably what happened. If all developers have is a hammer, everything looks like a nail. Our knowledge is crucial in finding the right solution for problems, not the other way around. Learning is a must, even things that might initially feel irrelevant. How a problem has been solved will say a lot about the programmer’s skills.
In the end, the code should work! It doesn’t matter how well structured and organised your it is. That should probably be the top of the list, and the first question we should answer is, “does it work?” :)
Code quality is like a diet
If you try to quit sweets, it will be hard to resist them, but eventually, you will reach a point when you change your natural “default settings”. Working with code works similarly. Make an effort to improve the quality, which will pay off later and become the natural “awesome default”.
“Excellence is not an act, but a habit”
Code quality is not something you do once, and you are sorted. Things are evolving, new features are added, and product requirements are constantly increasing. Web applications are living organisms, and you need to ensure the code quality is part of their DNA like calories are part of doughnuts.
Knowing & Doing
Knowing all these things means nothing if developers don’t apply them in the real world. When engineers are asked, “What is good code?” which is one of my regular topics during an interview, their responses vary a lot. Most will mention variable names, structure, styling, and maybe documentation. These are all the obvious things, but rarely can they explain in detail what they really mean. Especially when you start looking for answers which require considering the whole team in the context of writing good code.
How people speak about quality code says a lot about their focus. Whether they are self-centric or understand that writing good code has almost nothing to do with what THEY want, it’s all about others.
