Commenting your code

It’s been a while since I blogged. I was actively following lot of topics, but mostly held my thoughts to myself from writing.

One such article I read was: Who needs comments? My code is self-documenting! aka: Comment tersely with value-added information.

The author makes the following point:

/* If the first field of the properties record is N... */
IF master_list(l_curr_index).properties_flag.field1 = 'N' THEN

a better way of writing it would be

/* If the customer is not eligible for a discount... */
IF customer_not_eligibility (l_curr_index) = 'N' THEN

As part of the suggestion, he suggests it is better to write a function, and code the business validation. Once that is done, there is no need for the preceding comment. The function is self explanatory.

I know coding style differs. But I am particularly edgy about a function returning TRUE for a negative check (I know, I know, it is just me, but still saying). I would rather rewrite the following:

IF customer_not_eligible (l_curr_index) THEN

into

IF NOT customer_eligible (l_curr_index) THEN

this way, I can use the same function to see if the customer is eligible (otherwise, you would be doing, “IF NOT customer_not_eligible (l_curr_index) ” which is double negation and could be confusing.

How would you do?