Yes, I understand your frustration with the silly rule. I've read lots of programs with useless comments like
x = x + 1; // add 1 to x
And I say to myself, So THAT'S what a plus sign means!! Wow, thanks for telling me, I didn't know that.
But that said, the customer is paying the bill. Therefore, you give them what they want. If I worked at a car dealership and a customer said he wanted a pickup truck, I wouldn't argue with him about whether he really needs a pickup truck and quiz him on what he expects to haul in it. I'd sell him a pickup truck.
Okay, there are times when what the customers says he wants and what he really needs are so far apart that I try to discuss the matter with him, maybe convince him to agree to something more rational. Sometimes this works, sometimes it doesn't. In the end, if I can't change his mind, I give him what he wants. If he comes back later and says, Oh, that really didn't satisfy my business requirements, then we can charge him more to do what we told him to do the first time. How much you can negotiate with the customer depends on how much they trust your expertise, how their contract with you fits in with the organization, and, frankly, how bull-headed they are.
It would be a very rare case where, assuming it was up to me, I'd lose a contract because I thought the requirements were ill-conceived.
Bear in mind that the people that your company is negotiating with may or may not be the ones who invented this 25% rule. It could be a rule imposed on them from higher up.
I see five possible responses:
One. Convince your boss or whoever is negotiating with the client to argue about this. Odds are this will accomplish nothing, but you can try.
Two. Refuse to do it. This will probably get you fired, or if the company agrees with you, cause you to lose the contract. This seems unproductive.
Three. Write useless comments to fill up space, the sort of comments that just repeat what's in the code and that any programmer capable of modifying the code could see in 2 seconds. I've seen plenty of comments like this. Years ago I worked for a company where we were required to put comment blocks in front of every function that listed the parameters, like:
/*
GetFoo function
Parameters:
name: String, contains name
num: int, the number
add_date: date, the date added
Returns:
foo code: int
*/
int GetFoo(String name, int num, Date add_date)
The objection that such comments are a maintenance burden because you have to keep them up to date is not valid. There is no need to keep them up to date because no serious programmer will ever look at them. If there's any question about that, be sure to make clear to all the members of the team that the useless, redundant comments should be ignored. If you want to know what the parameters of a function are or what a line of code does, read the code, don't look at the useless comments.
Four. If you're going to add redundant worthless comments, maybe it's worth the time to write a program to generate them. Something of an investment up front, but could save a bunch of typing down the road.
Back when I first started in this business, a company I worked for used a program that was advertised as "Writes your documentation for you! Complete documentation for every program!" The system required that we give all variables essentially meaningless names and then have a table giving a meaningful name for each variable, so basically what the "automatic documentation" did was replace the meaningless name that it forced us to use with a meaningful name. So for example -- this worked with COBOL -- you'd have a line in your program that said
MOVE IA010 TO WS124
and they'd generate a line of "documentation" that said
COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE
Anyway, one could surely write a program to generate equally worthless documentation fairly easily. Read a line like
a=b+c
and generate the comment
// add b to c and save result in a
Etc.
Five. Make the best of the silly rule. Try to write useful and meaningful comments. Hey, it could be a good exercise.
Oh, by the way, may I add that you can always game the metric.
I recall once an employer said that they were going to start measuring the productivity of programmers by how many lines of code we produced per week. When we were told this at a meeting, I said, Great! I can easily boost my score. No more writing
x=x+4;
Instead I'll write:
x=x+1;
x=x+1;
x=x+1;
x=x+1;
Loops? Forget it, I'll copy and paste the code ten times. Etc.
So here, if they're going to count lines of comments, make each line short and continue the idea on the next line. If there's a change to what goes in the comments, don't update the existing comment it. Put a date on it, then copy the entire text and write "Updated" and a new date. If the client questions it, tell them you thought it was necessary to maintain the history. Etc etc.
