It is a painful truth that most of my fellow developers don't care about code readability and maintainability. Sometimes its frustrating to make changes on an unformatted, in other words poorly written code.
Code that we write represents our brain and I consider my code as how an artist considers his painting.
After reading an article on Style matters, I thought of writing this post on few important readability factors and how important it is to have your source code neat.
Top 5 readability & maintainability factors
Code that we write represents our brain and I consider my code as how an artist considers his painting.
After reading an article on Style matters, I thought of writing this post on few important readability factors and how important it is to have your source code neat.
Top 5 readability & maintainability factors
- Documentation with proper comments
- Formatted code with proper indentations
- Organized file folders
- Proper naming conventions
- Never use deprecated code
Comments & Documentation
A good developer learns a project just from the code; javadoc plays a significant role in the learning process. Imagine that all open source projects and JDK code with no comments and documentation. I am sure that it would at least take 10 times more effort to figure how to use them. A good javadoc in your application saves enormous amount of time for fellow developers.
All IDEs shows help texts for a method or class on mouse over for quick assistance, remember they all come from the javadoc of that method or class. When you leave your code with no comments, then you are letting some fellow developer to be handicapped in some way.
Formatted code with proper indentations
When my sister write Java classes in notepad for her college project, it is acceptable to have a code which doesn't have a decent formatting. Considering the modern IDEs that we use, formatting takes a few seconds. It has to be a habit to write formatted code and not for the sake of your manager or your lead wants it.
To the least there are options to do a format at your project level which formats all your classes in the project. For example using eclipse, "Right click on your project -> Source -> Format". Boom all your code is formatted decently with the basic code formatting settings, however you can go and edit the settings as you want and also you can share it across your team as an xml file.
All IDEs shows help texts for a method or class on mouse over for quick assistance, remember they all come from the javadoc of that method or class. When you leave your code with no comments, then you are letting some fellow developer to be handicapped in some way.
Formatted code with proper indentations
When my sister write Java classes in notepad for her college project, it is acceptable to have a code which doesn't have a decent formatting. Considering the modern IDEs that we use, formatting takes a few seconds. It has to be a habit to write formatted code and not for the sake of your manager or your lead wants it.
To the least there are options to do a format at your project level which formats all your classes in the project. For example using eclipse, "Right click on your project -> Source -> Format". Boom all your code is formatted decently with the basic code formatting settings, however you can go and edit the settings as you want and also you can share it across your team as an xml file.
Organized file folders
During several code reviews that I have witnessed project documents kept under "src". One common answer I heard from developers was its easy to access. I was shocked to see project documents going inside your deployable files. A good java project should have well organized packages which very well represents OO design being followed. Writing everything in the same folder makes it unmaintainable as the project grows.
Proper naming conventions
In most cases the people who maintain the code is not same as the author. They may not be knowing the project as good as the original author, or may be less skilled programmers compared to the author. Having very good class, method and variable names makes it very much easy for the person who maintains it. Reading java code should more or less be similar to reading english. Following descriptive naming convention helps to understand the code much faster. Using i, j, k, abc, xyz as your method or variable names through out your project makes it almost an unsolvable puzzle for people who follow. Sometimes it makes it tougher to debug for even the author who wrote it.
During several code reviews that I have witnessed project documents kept under "src". One common answer I heard from developers was its easy to access. I was shocked to see project documents going inside your deployable files. A good java project should have well organized packages which very well represents OO design being followed. Writing everything in the same folder makes it unmaintainable as the project grows.
Proper naming conventions
In most cases the people who maintain the code is not same as the author. They may not be knowing the project as good as the original author, or may be less skilled programmers compared to the author. Having very good class, method and variable names makes it very much easy for the person who maintains it. Reading java code should more or less be similar to reading english. Following descriptive naming convention helps to understand the code much faster. Using i, j, k, abc, xyz as your method or variable names through out your project makes it almost an unsolvable puzzle for people who follow. Sometimes it makes it tougher to debug for even the author who wrote it.
Never use deprecated code
A method or class is deprecated when a code is "buggy" or "inefficient" or for a "bad coding practice". And it is represented with @deprecated annotation. A good API would always give an alternative better option before deprecating the existing one. Look for the alternative option and never use deprecated code.
Note: All the points discussed here are for code written Java and may be applicable for other programming languages too.
