10 Basic Rules To Make Your JavaScript Code Easy To Understand
Save time by improving the readability of your code
Introduction
Imagine that you are trying to assemble a new desk but you can’t understand the instructions. Imagine that you’re in a hurry and you need a single USB cable, but after checking your drawer you found a bundle of tangled cables and you can’t simply take one of them. Those are similar feelings to the ones developers have when they need to change something in poorly written code.
Machines understand code far better than humans, but developers are the ones who write and maintain it. Keeping code readable is really important for teamwork; it saves a lot of time, mistakes, and frustrations. There are a few basic rules that will help you with that.
1. Use a Linter and Code Formatter
Even the best story would be hard to read without proper formatting, and it’s the same with code. Taking care with the format and keeping it coherent across the entire codebase would be a tough mission. Fortunately, tools like Prettier do that for you. Prettier comes with a default set of formatting rules, which can be easily customized with .prettierrc.
Another very useful tool is ESLint, which can find and fix syntax errors and other possible issues with JS code. It’s also possible to enforce some practices by creating custom rules, which makes it a great tool for ensuring code quality within the project.
2. Use a Single Naming Convention
PascalCase, snake_case, camelCase or UPPER_CASE? When the naming convention is well-defined, you don’t have to remember the exact spelling of a specific variable. Mixing different conventions is just confusing.
When creating JavaScript, Brendan Eich followed the same conventions as Java — camelCase for variables or methods and PascalCase for constructor functions — and JS developers usually do the same. However, if you are working with existing code using different naming conventions, it would be better to follow those.
3. Verbs for Functions, Nouns for Variables
This is a really simple naming rule, also taken from Java.
Thanks to that, it’s easy to guess what’s behind a specific name, without searching for the original definition.
4. Getters and Setters
And one more rule about naming: You should use get and set prefixes only for getters (functions allowing something to be gotten) and setters (functions allowing something to be set).
Using getters and setters is a common way to disallow a value’s direct manipulation. As getters are supposed to retrieve a value, the last thing you’d expect in a getSomething method would be the side effect of changing the object’s state.
5. Shorter Methods
Reading and understanding a lot of code at once is really challenging, so writing functions containing dozens or hundreds of lines of code is a really bad idea (and usually breaks the single-responsibility principle). Instead of that, you should create more but shorter functions with descriptive names. That allows another person to focus on the general idea and skip low-level details if understanding them is not needed.
6. Avoid Comments
Writing a comment is usually describing logic already described by source code. In many cases, comments are just workarounds for poor code quality. Pay attention to readability in the first place and usually you won’t need additional description to explain what is going on. Proper unit test descriptions are also very helpful, as they allow developers to quickly understand different use cases.
7. Use Positive Conditions
This one is determined by psychology: For humans, it’s easier to understand a positive context than a negative one. It doesn’t mean that we can’t read negative conditions, but it will take a bit more time and focus.
8. Use an Early Return Pattern
Long chains of conditions and nested conditions aren’t easy to follow. Instead of them, use plain conditions to return from the function as soon as possible and make your logic easier to track. Split your function into smaller ones if you have to execute some code after checking conditions.
9. Avoid Typos
This one should be obvious, but unfortunately, many developers tolerate typos in their code. In a project with proper names and a single naming convention, even someone not familiar with its details can search for something specific and navigate to the part that is interesting to them. When there are typos, it’s not possible. Typos make it easy to miss something when applying changes across the project as well.
Nowadays IDEs allow you to rename a JS variable/function/export with all occurrences, so even if you missed the typo before, fixing it later shouldn’t be an issue. You should not ignore them during a code review, either.
10. Avoid Unnecessary Complexity
The famous KISS (“Keep it simple, stupid”) principle is really crucial for code readability. Even if you follow naming conventions, keep your functions short, etc., it won’t be easy to understand what your code does if it’s over-engineered. This principle is much easier to follow if you adopt one of the extreme programming rules: “Never add functionality early”. You cannot predict what changes will be required in the future, so building in advance something that “might be useful” is ineffective and just makes your solution more complex than required.
Please note: This rule works great for implementation details. When it comes to designing an entire solution, you have to consider the bigger picture, and as a result, you might prefer more flexibility. An example would be adopting internationalization in an early stage in an app for an international client, even if initially only the English language is required.
Never Compromise on Readability
Poorly written code is like a time bomb. Sooner or later there will be a need to change or fix the way it works, and then instead of focusing on the task, you will struggle with understanding it. If you see any issue, just fix it. If you have already spent a lot of time on understanding some poor code, refactor it till you remember what it is about. Apply small improvements on a daily basis and after some time, the quality would be much better. That’s the only way to keep your app easy to maintain in the long term.
Thanks for reading. I hope you find it useful. Feel free to leave a comment, and never stop improving!
