Importance of Writing Code Comments in Software Development

Every developer knows that 80% of the time, the code is read than written during the software life span. If somebody does not know this fact, its better to know this now. Have you ever stayed late at office understanding the legacy code written by a developer other than you some 10 years back and had tough time understanding it? This has been the challenge in maintaining the software systems over the period of time. The documentation work done for the coding work will almost be out of sync with the current code over the curse of time. So the documentation or the design artifacts do not help in understanding the code logic simply because they were never updated when some body changes the code. I agree that design document helps understand the code at high level, however to completely understand the code logic, its only the person writing the code who needs to write comments for others.

In this article I'm going to write about why code and comments go out of sync and what can be done to ensure the better code comment quality during software implementation phase of the software development life cycle.

What leads to poor code comments?

1. In a typical product development company, the software is written once and is read/modified for maintenance after releasing the product to the market. The maintenance activities could be either bug fixes or new product feature implementation. The focus will be to fix those and release without planning to go back to the original design or forgetting to see if the comment written is still valid after modifying the code. 85% of the time, the developer forgets to correct the code comment after modifying the code.  This may happen because the time allocated for fixing the issue is not sufficient to consider the design and re-look into the comments.

2. I heard from one of my fellow worker saying that "the Software complexity is directly proportional to the number of developers who developed the software!". And yes in-fact this is very much true. I've seen cases where there is no common understanding between the developers. Each developer is on different page and obviously they can't create a better software. The mentality of the developer that the code is already legacy and no one bothered to write comments and why should I  correct somebody's comments?

3. Comments are not 'executed' by the computers. So why write comments if the goal is to complete the given coding task? Well, it would have been so nice if compilers themselves write code comments on behalf of developers!  May be this is feature enhancement for compilers!!

How can we maintain better code comments?

1. Impose the rules. Add in the code review checklist that the code comments are 'well' written and importantly ensure that code reviews are carried out without fail. This is true for code being written from the scratch or code being modified for maintenance activities.

2. Have the habit of writing comments first before even writing the code. Its usual tendency of the developer to forget writing comments after writing the code.

3. Encourage developers not to write the obvious comments such as 'Loop through the array' and code a loop next. I still do not understand why some one writes so obvious comments that are absolutely not required. Such comments can easily be understood by looking at the code.

4. Make it a mandatory habit to write 'Why?' part of the comment. This part is most commonly missed in the code comments. Take an example:  int nValue= file1.length() + file3.length(). In this example, why not file2.length()? If developer does not write this information then nothing can help understanding this code neither the design nor the requirements that are high level.

The benefits of writing quality code comments are very obvious.  

1. The developer reading the code can go home early. (no late nights).
2. You can reduce the potential software bugs that might have been caused due to code changes without understanding the completely why the code was written. 
3. Make software developers' life easy and enjoyable at work.
.... I can keep adding several things here.

Conclusion

There are no hard rules here. If your software code does not have better quality code comments, then an activity of just improving the code comment quality can be taken up. Believe me that this practice plays a great deal if the same code is being modified for feature. Better code comments are speed up the code refactoring activities which is performed to build a new software product but reusing the existing code.

Have a look at Code Smells & Coding Standards.

This article is dedicated to all software developers in the world. If feel like sharing the frustration of understanding the code with no comments, leave me a comment.

Rules For Code Reviews In Software Development

Code reviews are important in any software development processes to ensure the late failures of the software systems. Though code review does not add any value directly to our customers, its indeed required since the review is second level of confidence on the implementation work. There are different types of code reviews. While static code reviews ensure the syntax and coding guidelines correctness, the reviewers review code for correctness of the program logic and affected code areas. Following are some guidelines that people can pick based on what works best for them. The guide  lines vary among different software development teams and there are no rigid rules.

In this post I'm going to write about the code review guidelines and some best practices that we can follow during code reviews.

1. Avoid checking-in the code that is not reviewed. This is because in a bigger software system, any change made can have impacts on other software modules. Have the code at least peer reviewed.

2. Reviews can be piled up if the reviewer is not available and number of reviewers are less compared to developers. When I say 'reviewer' it means that some one who understands the system as a whole and knows the system architecture. This helps finding the impacted areas of the code changes. In this case files can be checked and then the revision numbers can be noted down and sent for the review.

3. Code review is challenging because, the review expertise comes from experience dealing the software systems and code review requires domain knowledge too. Based on the nature of the software i)Software Product 2)Software services. 

4. Checklists play a great deal during the code review. The review checklist can be customized based on the type of software. For example, does the code change impact xyz module? Does the change takes care of backward compatibility.

5. Let the code not lie local to a system for more than 3 days simply because its not reviewed. Its fine to check-in the code if the review is getting delayed to make sure that the work is not lost.

6. Checked in code can always be reviewed before the new change goes to the production and hence there is no harm checking in the code that is not reviewed. It only requires to ensure the reviewer does review the checked in code without missing any revision.

Sometimes the code review involves going back to the design and seeing if the code is written as per the design (if the design is present).

Code review is not for testing somebody's programming skills and suspecting some body does not write better code because any developer's, even experienced one, can go wrong in a complex software system. And hence ensuring code reviews (not for just following the process) is essential to get better code quality.

Google Voice - An easy way to make international calls

Google voice is been in the service for quite a time now continuously improving on the call quality. Using Google voice you can now call a mobile, office, work land line phones from computer system or even from your own mobile! Yes, you can opt for a Google access number which can be used to access your voice mails and make calls. Its a unique number given to you from Google.

My personal experience is that when I traveled to USA, the easiest and quickest way to call home was the Google voice. Otherwise, to buy a phone and a sim card and calling cards, you need more time.

Following are the some of the Good things I feel about Google Voice

1. Local calls are Free (USA and Canada)

2. International calls are very cheap.

3. Better manage you voice mail. Customized voice mail greetings can be configured.

4. You can use Google Voice with a brand new number from Google or your existing mobile phone number.

5. Easy method for adding calling credit.

6. Google voice can be configured to call multiple phones based timings, such as office, work, mobile phones.

7.  Good call quality except very rare cases.

8. You can get your credit refunded if you wish not use Google voice.

9. Google voice can be configured to send email whenever your friends call you etc.

10. Call and billing history can be viewed at any time.

Google voice is very convenient  when you are traveling the world to make calls without worrying about which service provider to go for and what are the best calling card options etc. This is true at least at the initial time of your new travel place. Google voice was very handy for every body when I shared this information with my friends and hope this helps you tool.

Google.com/voice for information.