Clean Code

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.)

Tips to write clean code

• 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:
  • Data
  • Object
  • Info
  • Information
  • Variable
  • String

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)

Bad convention:
   if(age>=18) "eligible for voting"

Good Convention:
   MINIMUM_AGE_FOR_VOTING=18;
   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.

Conclusion

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.