Improve the Readability of Your Software Code
When writing code for a program, it's easy to fix all of the bugs and have it compile correctly, but making it easy for another person to read it is much harder. Here are some tips that will help you improve your code's readability.
Steps
- People who maintain code are never as well versed as the original author. They may have poorer programming skills and will know less about the project. This is the person that you are writing the program for. You want the code to be easy for this person.
- Just because a language feature is available in a language, doesn't mean you should use it. The goal is to communicate what the code does to the next reader, not to impress him with how few lines you can take to write code.
- Often an algorithm is difficult to follow. But often it is published somewhere. Place the URI of the documentation for the algorithm in the comment section for the code. If the URI points to a location that is ephemeral, then copy the information somewhere where the code maintainer can find it.
- Reference the coding standard in the header of the file. Provide a file if possible that tools can open to incorporate the correct settings. As an example Eclipse defaults to using tabs, but tabs are rendered differently on different text editors. Using white space instead of tabs may be preferable but having a file that provides the proper settings for a project.
- Use white space. Skip lines between code that does different things, and use spaces after semicolons and commas. This will make your code look cleaner and easier to read.
- Indent inside curly braces. This makes it so that it's obvious that a chunk of code is separate from another. This can help when writing a long method. Indenting inside if statements and loops will make it easy to read. This technique is called nesting, that is it shows a chunk of code is "nested" within another chunk of code, and allows the reader to easily follow the nesting pattern.
- Write descriptive comments. Assume the person reading your code knows nothing about what it's supposed to do. Your comments should explain every step of the way. All of your advanced, confusing, or complicated algorithms should be well commented. Also, try to describe what purpose the code has. For example, instead of writing "add one to variable," say why this is important in the code, as anyone can see it is incrementing the variable, e.g "increment the number of page hits by 1".
- Make your code "self-documenting" by creating descriptive object names that describe what their purposes are. Objects should either reference the domain of the problem or standard software artifacts. A List is a List. You may have to create a Customer List which subclasses or implements a List. Variables and function parameters should have descriptive names.
- Include the original author and the current maintainer of the code in the initial comment of the file. This tells people who to go to to service the code.
- Comment often. Write comments to indicate your intent. Over commenting your code will lead to someone deleting your comments.
Tips
- Making your code easier to read will also help you debug your own program, making it easier on yourself.
- Constant variables should be in all caps, with words separated by an underscore. Regular variables should have the first letters of each word be capitalized, omitting the underscores.
- Add white spaces if they are allowed.
- If you want to comment a large chunk of text, use "/*" to start the comment and "*/" to end it. Then, you don't have to write "//" on every line. (Note that making comments may be different in other languages)
- Find your style of writing code. There are a variety of styles you can use, such as the following examples: myVariable, MyVariable, myvariable, MYVARIABLE, My_Variable, MY_VARIABLE, my_variable, my_Variable, My_variable, and more. Make sure you assign each style to a specific type such as MY_VARIABLE for constant variables and myVariable for regular variables. Just make sure that you stay consistent through style. You don't want to end up having both myVariable and MY_VARIABLE constant variables.
