How to write better Code
by Chathurika Sandarenu
Quick recap
Before starting this month’s article let’s have a very quick recap of what we discussed in my previous article. Last time we discussed few points, which make our software difficult to maintain, overdue and costly. We also looked at few key points which make our software better and help us to avoid lot of maintenance issues. I’ll briefly list down those points here. I highly recommend you to read my previous article and get these points in to your heart.
In terms of best practices, last month we discussed about importance of using common coding convention among whole team. We also discussed some useful tips on how to name different programming artifacts such as variables, functions, classes, etc…
In this article I’ll discusses some more points which helps us to write better code.
Comments
Comments are very important aspect of good programming. Comments are very helpful to understand the code. This can be very handy during maintenance face, since most of the maintenance is done by different set of programmers. But as with any other thing comments are also not 100% good. They can also make it extremely difficult to understand code. Using comments to describe bad comments can make things much worse. Hope you can remember that in my previous article, I told you use meaningful names rather than putting a comment.
Many experienced programmers discourage the use of comments to describe what code does. What they argue is that if some piece of code is difficult to understand, don’t use comments to describe. What we should do is to refractor our code to make it readable. Check the two code fragments given below and see which one is much readable. Consider the two fragments of code given below.
Second if statement is much easy to understand. When writing code you can start with a statement similar to the give first code fragment and later refractor it to more cleaner second format. For that you can easily use refactoring tools provided with your IDE.
Another issue with comments is that sometimes they lie and misleading. Yes, that is true. During the lifecycle of a project you may change the way a function operates, data formats you use, etc… but forget to update the comments you have placed previously. Well, you may think that this not something wrong with the comments itself, but the programmers should be little bit more disciplined. Yes that is true, but don’t you think that rather than putting comments, letting your code to speak itself?
Let’s have a quick look at some good and bad comment types.
Good comments
Informative comments
It is sometimes useful to provide some basic information through comments. Look at the sample below. It describes the sample format which the regular expression is trying to match.
Intent revealing comments
Yes, code has to be clear and self expiratory. There is no question about that. But doesn’t matter how clear your code is, it can only tell how the program is working, but not why. For that we have to use comments. We can use comments to tell why we use particular algorithm, why the calculation is done this way, etc… But here also we have to be careful that comments are not misleading.
API documentation
comments
API documentation comments in another must have, if you are developing some kind of public API. Clear and descriptive Java docs can save lot of developer’s time and reduce lot of confusions. But when writing comments, you have to be careful not to fall in to any traps which we discussed earlier.
TODO comments
Sometimes we come across situations where we cannot implement part of program logic due to some reason at this moment. In such situations we can leave TODO comment there, so later we can come bsck and implement the logic. TODOs are tasks for us that we have to do in the future. All of the modern IDEs such as Eclipse, Idea, Netbeans or Visual Studio provides tools which can track all TODOs in the code. So when the time permits we can go through all the TODOs and implement without missing out anything.
Bad comments
Redundant comments
Redundant comments are the most common form of bad comments. We put comment just because we feel it is better to put some comments. Most common form of redundant comment, is variable commenting.
This is completely useless. Even though we have used java doc comments they don’t provide any documentation purpose. Best practice is to use self descriptive variable names and remove all comments. It makes the code more clear and readable as well.
Closing braces
comments
Sometimes we use comments to keep track of closing braces of in a large function, which involves lot of conditions and/or loops. In such situations, question we have to ask is why this function is this large? Ideally functions should be very small and should do only one thing. Your function has become large and filled with lot of conditions and loops since you have tried to achieve lot of things inside one single function. Best solution is to refractor the code in to small functions rather than putting comments.
Commented out old code
This is one of the worst kind of comments. We comment out some piece of code due to some reason and keep it that way without removing it completely from the source file. Well, we may comment some code in order to test something, change logic, etc… but we should clean the source code once we finished the testing. Other developers in the team also don’t dare to delete these commented codes, since they think that they are there for some reason. Finally these commented out code fragments collects and make your code really ugly.
If you are using good source control system, then you should not be afraid of deleting out your pervious code and add new code rather than commenting previous code and let it dirty your code. Source control system will keep track of the changes you made to the code, if needed you can rollback to older revision.
Comment First development
So far we have discussed how to use comments to improve our code quality. In additions to these discussed good uses of comments, some developers use “Comment First” development practice. There we write comments before writing any code. I’ve practiced this and it is really affective. Especially if you are starting to program some complex algorithm or calculation, it is better to put steps which you need to be done as comments. It helps you to collect your thoughts before start coding.
Post new comment