Untitled

A few Comments on Comments

/*

********************************************************

You are not the owner of the code that you write. The owner is always the organization who you are working for, or the customer who you write the code for. So, please write proper Comments with your well-designed and beautifully-working source code, so that it helps you and other developers during and after the development cycle.

********************************************************

*/

Let us talk something specific than general suggestions.

What does proper mean here? Is it proper style and syntax?  Is it writing in proper place?  Or Is it writing proper text?

So, how about a few comments on Comments:

//

// Don’t hesitate writing a long Comment when it is necessary.

// Don’t sacrifice Comments for a beautifully-looking code.

// 

// ‘Purpose’ of a Comment overrules ‘Beauty’ of code. 

//

// Don’t just explain the WHAT part but explain the WHY part.

// Most of the times WHAT is more obvious with proper coding standards.

//

Example:

// Sleeps for 5000 ms Thread.sleep(5000);

The above doesn’t serve any purpose. Rather, something similar to the following comment would serve the purpose right.

// (What) Allow time for the input processing. // (Why) From the testing performed, it usually takes around 2000-3000 ms in normal // workload scenarios. So, using a 5000 ms delay to be on a safer side, considering // significantly higher workloads and at the same time not slowing down the processing time. // (Why for future) When we support xyz interface in future, we need to revisit this interval. // We need more time delay to be allowed on xyz interface. // So, the performance with this interface might be a bit compromised. //… //… Thread.sleep(5000);

//

// Don’t add Comments which are very obvious.

//

// Comments and Coding Standards are Complements but NOT

// Replacements to one another.

//

Example:

// Copy all elements, field by field, from source to target. for(…) src = getNextSrcElement();

target = geNextTargetElement();

// copy src name to target name

target.name = src.name;

// copy src title to target title

target.title = src.title;

//Allowed bonus is 50% more in target per the following requirement

//….

//….

target.bonusLimit = 1.5 * src.bonusLimit;

…

…

…

//

// Necessary Comments are MUST than GOOD-TO-HAVE. //  // Working-code is a subject of your Design and Coding skills and it is for your // Compilers and Computers;  // Explaining-code is a subject of your Comments and Coding Standards and  // it is for us, the Human-beings. //

Fixing an ‘Undeclared Variable’ error is a MUST situation that your compiler creates for you. Fixing an ‘Unexplained Code’ is a MUST situation that you need to create for yourself.

————————————————————————————- I don’t believe poor Comments have impact on Quality !!! ??? They are just plain text.

  Yes, they may not have immediate or direct impact and that’s probably why some developers safely put them on the back burner. But in the long run, here are some of the bonus items offered by an ‘unexplained’ or ‘improperly explained’ code.

— Removing/Modifying a line of code which shouldn’t have been and thus attracting regressions. — Longer cycles to understand the code as part of code reviews, bug fixing, code extensions etc.. — ———————————————————————————

So, the inference is:

// Our goal is not ‘writing Comments’ but it is ‘writing some useful information, which cannot be conveyed just though the executable code, in the form of Comments’.

// Write ‘Necessary and Sufficient’ Comments maintaining the balance between Readability and Maintainability of the code.

// Once you have written the Comments, read them ‘from the future’ point of view and ‘from the eyes of the other developers’ to ensure the Comments are serving their purpose right. If you want to understand ‘why’, try reading your own code (without comments) that you have written a few weeks back.

After thought:

Does your team understand what ‘proper’ Comments mean?

Does your team understand the role of proper Comments in the long run maintenance of the code?

This blog first appeared in “Beyond your Code” on 28 Aug, 2012.

<!-- if(wpa2a)wpa2a.script_load(); //--><!-- if(wpa2a.targets)wpa2a.targets.push( title:"",url:""); if('function'===typeof(jQuery))jQuery(document).ready(function($)$('body').on('post-load',function()if(wpa2a.script_ready)wpa2a.init();wpa2a.script_load(););); //-->