Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
– Martin Fowler
Writing clean, understandable, and maintainable code is a skill that is crucial for every developer to master.
When I say clean code I mean:
- Proper variable name, function name, class name, proper indentation, proper spacing, proper comment, and proper/unique code style throughout the team.
- Minimal number of lines of code, classes, functions, etc. Less code means less headache, fewer bugs, and less maintenance cost.
- No duplication of code. Duplication in your software shows bad software and lack of knowledge.
- It might seem contradictory to my previous point but too much abstraction is also bad. If your abstraction forces you to add more conditions and extra parameters in your method every time a new feature is introduced, it is a bad/wrong abstraction and you should follow the below things:
- Try to find a way so that every time you introduce a new feature, your abstraction should not be affected.
- Go back to duplication. You heard it right. Duplication is always better than wrong abstraction.
Well, I don't see this as a failure of abstraction. It's caused by some specific other failures.
a. Failure of people to understand data modeling, and the
difference between interface and implementation. "A new
requirement appears for which the current abstraction
is almost perfect. Just because the code is the same
doesn't mean it should use the same abstraction. The
data model is wrong, not the abstraction.
b. Failure of people to think of the entire system, when
making a change. The rookie mistake is to think that
adding one more conditional is always harmless, but, at
some point, you've got 3 tons of straw on that poor
camel's back. Adding just one more case may have been
the correct fix last week, but not this week.
- No magic numbers (A magic number is direct usage of a number in the code). Magic numbers are bad, not readable, hard to maintain and not reusable.
- Minimum/No hard coding. It is bad, not reusable, not testable, and not maintainable.
- Code should pass 100% of test cases(even 99% shows that you are screwed).
- Code is easy and cheap to maintain.
- Mature programmers know that the idea that everything is an object is a myth. Sometimes you really want simple data structures with procedures for your task. So you have to carefully think what to implement also thinking about the future perspective that what will be easy to update.
Always write concise documentation of your code( classes, functions, properties, etc.)
- Variable, function, or class names should be descriptive. If it requires a comment to describe what the name does, it's a bad naming convention.
let s; // number of seconds ---> Bad naming convention
Good naming convention:
let numberOfSeconds, customerName, employeeName, mailMessage, mailFolder
- Do not include any redundant information/ noise words in naming. Some of noise words:
Bad naming convention:
userInfo, userData, userVariable, userObject, accountInformation, employeeString etc.
Good naming convention:
user, employee, account etc.
- Be consistent while naming variables of similar tasks. For example, while naming any variable which stores fetched data from an API call or Database use only one of these: get, retrieve, fetch. Don't use more than one as they do the same task.
Say you decide to follow get convention:
getUser, getName, getFile, getAccount etc. ==> Good convention
getUser, retrieveAccount, fetchName ===> Bad convention
- Don't use magic numbers(A magic number is a direct usage of a number in the code)
if(age>=18) "eligible for voting"
if(age>=MINIMUM_AGE_FOR_VOTING) "eligible for voting"
Avoid leaving code inside comments because it makes other developers scary to remove them as they don't know whether it is for comment purposes or left to use later.
Always follow the coding style defined by the programming language which you are using. Few conventions in Typescript:
- Variable name should be in the camel case.
- Function name should be in the camel case.
- Class name should be in pascal case.
Try to follow the DRY (Don't Repeat Yourself) principle.
Function name should be a verb.
Class and variable name should be a noun.
Prefer to use code formatters such as Prettier for better code arrangement.
People often ask me, what should be maximum length of variable, function or class name. Well my answer to them:
If there's a shorter, but yet descriptive way to name the function, variable or class then your current variable, class or function name is long.
The skill of writing clean code comes from using it again and again in software development. It is the least you should follow while writing a software code.