Best Practices of Coding
If you have been coding for two or three years or even more than that, you have probably been significantly slowed down by a messy code. Being a professional you would read some 100x lines of code compared to what you write. Over the span of a year or two, teams that were moving fast at the beginning of a project can find themselves slowed down due to the messy code written by their teammates.
A programmer with code sense can understand a messy code and recognize a mess but will have no idea what to do.
Now, we have understood how important it is to write clean code, but “what is clean code?”
Clean code can be read, and enhanced by a developer other than its original author. It has meaningful names. Code should be literate since depending on the language, not all necessary information can be expressed clearly in code alone.
Few aspects to be considered while writing clean code:
- Meaningful names
- Use intention-revealing names
- Avoid dis informatic names
- Use pronounceable names
- Don't use single letter names which not reveal what they mean
- Class name should be a noun / noun phrase like Customer, Account. A class name should not be a verb
- Method names should have a verb or verb phrase like setNum, getNum, checkBalance.
- Refrain from using same variables with different purposes
- You can always use CS domain names, algorithm names, pattern names as the people who read your code will be mostly programmers.
- Functions should be small
- Functions should do one thing i.e. it should perform only one task.
- We want the code to read like a top-down narrative. We want every function to follow an order so that we can read the code.
- Choose a good name to the function so that it talks about its functionality.
- Function arguments - A function should have minimal or no arguments. Arguments are hard. They take a lot of conceptual power. Arguments are even harder from a testing point of view. Imagine the difficulty of writing all test cases to ensure all various combinations of arguments work properly.
- Don't ever pass a boolean value as an argument to the function.
- Make sure that your function has no side effects i.e. as mentioned above a function should always do a single task and should not affect any other literal/ variable values which it need not to do.
- Restructure and refine the function until it reads the way you want it to read, even if you start with long and complicated functions containing lots of nested loops or dis informatic names.
- Nothing can be helpful as a well - placed comments and nothing can be clutter up a code more than unnecessary comments
- If the programming language we use is expressive enough, or if we are able to express our intention enough with our code we do not need a lot of comments or maybe not at all!
- The proper use of comments is to compensate for our failure to express ourself in code.
- So when you find yourself writing a comment, think through and see whether there isn’t some way to express yourself in code.
- Remember that clear and expressive code with few comments is far better than complex code with lots of comments
- If you decide to write a comment then spend necessary time and make sure that it is the best comment that you can write.
- Let us look into few purposes where commenting your code would become mandatory:
- Legal comments - Comments about copyright and authorship statements
- Informative comments - Comments which talk about the task of a function. But it is always suggested to use proper names for such functions instead of writing the comment.
- Comments which explain the intention of the code written.
- TODO comments - explains why the function has a degenerate implementation and what the function’s future should be
Don'ts while writing a comment:
- Redundant comments - Don't write comments for redundant code snippets in any programming language.
- Misleading comments - It’s better not to write comments than writing some inaccurate or misleading comments
- Use proper function names or variable names instead of commenting their functionality
- Position markers - Don’t use a series of slashes or dashes just to separate blocks of code instead intend properly.
- Commented out code - Don't leave unnecessary lines of code commented out just like that. If you have completed working on the code make sure that you remove commented out lines which you used while testing.
- Vertical openness between concepts - Each line in a code represents an expression or a clause and each group represents a complex thought. Those thoughts should be separated from each other by blank lines.
- Vertical Density - Group the lines of code which perform a specific task into one dense code block.
- Vertical declarations - Variables should be declared as close to their usage as possible
- Vertical distance - Concepts that are closely related to each other should be kept closely to each other
- Dependent functions - If one function calls another function they should be kept close to each other and the caller should be above the callee.
- Indentation - Make sure your code is indented properly. It makes the reader understand the code much easier than that of unindented code.
- Finally, make sure to keep your lines shorter. Follow the rule that you never scroll to the right while reading the code. You can edge your lines at 100 or 120 characters for that.
Everyone can write code but writing a piece of code that every one can understand is an art.
Written by Deekshitha Kashetty, a Siliconvalley4u's student