My client wants 25% of comments in my current project, how to react? [closed]

Question

junior developer here.

I am currently working alone on a web application for a big client of my company. I started last month. The client wants at least 25% of comments in each of its software projects.

I checked the code of previous applications and here are my observations :

• each file begin with a comment block (package, date last updated, name of my company & copyright)

• all variables are commented with their names // nameOfCustomer public String nameOfCustomer

• all getters and setters are commented

• very few useful comments

It seems like developers just place as much comments as they can to hit that 25% threshold, regardless of quality and usefulness. My company tells me that "we do it as the client wants it".

I did not speak directly with the client about this. Here are my arguments so far :

• useless lines to read and to write (waste of time)
• comments are sometimes not updated (source of confusion)
• developers are less likely to use or trust real useful comments

What is your advice on this subject ? How should I handle the situation ?

Answer 1

All the other answers and comments here really threw me for a loop, because they are so counter to my first reaction and so counter to the attitude I've witnessed in my coworkers. So I'd like to describe an alternate approach, if only for the sake of being the dissenting voice.

The guiding principle of this answer is, "Delight the customer". Delighting the customer does not just mean meeting their expectations; it means understanding their requests so deeply that you can interpret what they say in the way they mean it, and delivering above and beyond what they ask for. Other answers appear to be guided by the principle of malicious compliance instead, which I find abhorrent; and besides is questionable business practice as it's a bad way to get repeat customers.

To me, when I hear the client say, "I want 25% comments", that is the beginning of a dialog. For me it is clear that the implication here is "I want a lot of descriptive text, so that newcomers to this codebase can get up and running quickly", not "I want you to add randomness in a certain syntactic category" as other answers appear to be taking it. And I would take that request seriously, and intend to write a lot of descriptive, helpful comments, guiding a newcomer to the structure of the code, pointing out surprising engineering decisions and outlining the reasoning that went into them, and giving high-level English descriptions of complicated code sections (even if they don't have any surprises). This intention and understanding is the starting point of the discussion -- that is before we even start talking. To me the implication of the request is so clear that it doesn't even need that clarification; but if to you it is unclear you should of course check in with them!

Okay, so where does the dialog go if that's the starting point? The next part of the dialog goes like this:

1. I would expect this to be a serious additional effort, possibly in a second phase of the project, that is above and beyond the production of the tool they care about working. It may be several minutes of discussion to discuss this process and why it is additional work, but I'm going to omit it here because as a professional programmer I expect you know how hard it is to make good comments.
2. "A serious additional effort" means we may need a longer time budget and a greater monetary budget; or we may need to reduce the feature budget; or we may need to compromise on comment quality and quantity. This part is going to be a bit of a negotiation. But in my opinion, you should be very up-front about the costs of doing this extra work, and make sure that it is such an important feature to the client that they are willing to take on these costs. And if they are -- great! You get extra time and money, and they get high-quality comments. Everybody wins. And if it turns out that the commenting feature is not so important to them that they're willing to lose the ability to flurgle widgets or willing to let the deadline slip to late Granuary, 20x6, then everybody wins again: they get the product they want, and you don't have to spend the extra effort it takes to create high quality comments.

Here is where I think the dialog should not go:

3. Don't threaten the client with low-quality comments. Let them help you choose the level of effort they want expended and that they are willing to pay for. Don't promise them 25% comments and then inform them that you intend to deliver on this promise by autogenerating randomness after the project is built.
4. Don't hide your plans. Don't promise them 25% comments, and then autogenerate randomness without telling them that's what you're going to do. When they notice (not if), you both lose big-time: they are unhappy with the product they got, and you get negative word-of-mouth.
5. Don't try to convince them they don't want comments. They clearly want comments. Discuss tradeoffs of various approaches: yes! Discuss alternative ways of making the codebase newcomer friendly: yes! Tell them they don't know what they want: eh, no. You want to work with them to get them what they want; so understand what that is and figure out how best to deliver that to them in a budget they approve of, prioritizing the features they care about most if the resources they have are insufficient.
6. Don't make excuses about how hard comments are to write. Writing code is hard; debugging code is hard; writing comments is hard. If it was easy, they wouldn't be hiring you. Just skip the complaints and get straight to the point they care about, namely how the extra effort required affects them.

Answer 2

The customer is king. So as contractor you shall meet whatever the client has defined as quality standard. Or you risk to be out.

This being said, it matters very much how the (here poor) quality standards are defined:

• Contractual quality standards: the delivered code must comply, or otherwise it's a breach of contract. No choice.

• Formal corporate quality standards: even if it works perfectly, the code that does not comply will be considered bad quality by so many people, that you'll be old before you have converted them all to a better practice. Worse: well known tools can be used to automate and legitimate such quality metrics (e.g. sonar cube). Almost no choice.

• Ad-hoc criteria defined by a couple of persons at the client's. Here you could engage discussion. There is hope :-)

In this last case, there could be some flexibility, and you could try to diplomatically make the point. Here some arguments that speak against the customer's criteria:

• Productivity issue: the coding is done twice (once in English and once in code).
• Accuracy issue: if changes are done in the code, they must be done in the comments, or the comments might become useless.
• Refactoring issue: as refactoring tool doesn't process the variable names in comments.
• Risk issue: ambiguity (or obsolescence) of comments could generate confusion and risk to increase bugs.
• Quantity is not quality
• This funny collection of useless comments on StackOverflow.
• This article that argues that a high comment ratio could even be the sign of a code smell.

But instead of speaking against the bad and confront the customer, may be could you simply promote better approaches:

• Clean code (suggest the book to your customer: there's a convincing section dedicated to comments and self-documenting code).
• Documentation practice: The most difficult things to grasp, and hence the most valuable information, such as for example the relation and interaction between classes is better documented in a separate document (for example in an UML picture rather than 1000 comment words ?)

If the customer is still not convinced, you could propose an experimental alternative, using tools generate automatically documentation with comments, such as javadoc or doxygen. Propose therewith to shift the focus from quantity (25% of code) to quality (generate an understandable javadoc).

Answer 3

The client wants at least 25% of comments in each of its software projects.

Does the client really want 25% of comments or does your client want your code to be as descriptive as possible?

IMHO, the client knows what he wants, but not what he needs. As a client isn't a developer itself and gets feedback from its own workers/customers, your client only sees the top part of the iceberg.

I guess your client has some pseudo-knowledge and wants code to be well documented and easy and cheap maintainable, and the tool for this are comments(in his mind).

Try speaking to him and prepare some code snippets with well written code that explains itself, and another bad written one with comments. Just a few lines. Show this if needed and use it as picture to your words.

Talk to your client/supervisor/whatever and try to tell them the modern principles of version control (no need for comments at the beginning of the file) and clean code (I recommend the book as well) and thus resulting self explaining code.

Maybe, if you can show it good enough and make your client understand that he wants clean code, not just comments, you and your team can write better code (with much less comments) and immediately show that you're a good developer worth keeping.

Answer 4

This reminds me of those silly Stack Overflow answers you see that consist of one line followed by, literally, "some text here to get to minimum character limit".

When this happens, arguments could be made that two groups of people are at fault:

1. The people who put in the limit — clearly it is excessive and prevents people submitting their properly-formed information without adding artificial noise

2. The people who submitted information that wasn't properly formed, then added artificial noise when the system prompted them to instead add more actual substance

Sometimes, a question will be both simple and on-topic, and there is not much more to say than a few words. However, this is exceedingly rare. In almost all cases, there is plenty more of substance to say. If nothing else, it should be blindingly obvious that the way to get around a character restriction is not to just dump random noise into your post.

This comments situation you're facing is almost the same. Your developers have taken a request for comments, and implemented it by dumping random noise into their code. Documenting the names of variables, right next to the variables' declaration, is vandalism. That should never have happened.

"But how else can we get to 25%?" By writing actual comments of substance. Use more words, better words, the best words to document the effect of functions. Expand on your explanations. Describe edge cases in more detail.

However, going back to the original point, the client is partially at fault here too, because "25% of the source code" is extremely arbitrary. Ultimately, though, they are the client, so make the best of it. But I do mean "best". Not "worst", as has been happening so far.

Answer 5

I don't know what's the big fuss about with this requirement.

Just by basic doxygenation of your code you're probably already at 10% or so. And let's take another 5% of comments you've written for yourselves (some write more, but 5% seems like a conservative estimate if you haven't taken a vow of silence). At this point it's around 15% (yes yes, I know, 5% of 90% is less than 5%, don't nitpick). If your doxygen is less than 10%, perhaps your methods are very long; it's usually a good idea to break them up into smaller (mostly private/protected) ones, or use more generic helper classes etc.

Now, for the rest of comment text - put design considerations and usage scenarios in class/file-level comments. Have some tables or ASCII-art (or doxygen code which generates nicer-looking stuff when it's rendered). I don't know, of course, what your project is about, but I believe you can do this with no dummy comments (other than the doxygenation boilerplate) and get to something close to 25%.

If it's only, say, 20% and not 25% - I'm sure the client just gave that number as something arbitrary, and will be fine with it. Anyway, have a talk with them to discuss what the comments should encompass; and show them an example commented file to see if they're pleased. If they are then that's it, if they think something is missing they'll tell you what's missing. They're not going to tell you "We can't suggest any possible extra comment but we still want you to add some".

PS - Look at the standard Java containers' code to see how you can reach, oh, 70% or so...

Answer 6

Having 25% comments in your code is an excellent goal to have, and it makes the client happy. Now writing 25% crappy filler comments like "i += 1; // increase i by 1" should be beneath you, so take your time, write useful comments, and enjoy the feeling that you are actually paid to do something you should do anyway.

Answer 7

We all know this is a crap requirement. The interesting question here is

how to react?

I'm a big believer in making problems visible. Here I'd use the fact that money talks.

Ask me to do this and I'll say sure, that'll add 1% to my bid. Oh but it'll add 20% to any future maintenance bids.

Only once they ask why will I teach them that the point of good names is to avoid the need to comment.

As an alternative, I'll propose creating documentation aimed at getting a maintenance programmer with a defined set of assumed qualifications up to speed on the ideas behind the project. Or sure, I could give you 25% comments. Up to you.

Answer 8

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.

Answer 9

Arbitrary metrics seem to be a fact of life in too many projects...

This is often seen in dumb requirements such as a maximum Cyclomatic complexity leading to more complex code, because functions are unnecessarily split up to ensure compliance, or files being split up because they exceed some arbitrary SLoC length

Comments should add to the code, and explain what is going on (and not just repeat the code!).

That said, if this is what your customer wants, and your company has agreed to provide, unless your QA Manager develops a dose of common sense, you're stuck.

Answer 10

In the short term theres nothing you can really do. Go along with it.

You should also ignore all the stupid ideas I'm seeing in this thread about passive aggressive protests and silly jokes within the code.

Once you have developed a trust relationship with the client, they'll be better placed to listen to your reasoning - you might find that this is a silly demand from one person who was once influential and that it has very little support in-house.

Under no circmumstances should you go against it without the client's permission.

Answer 11

I am disappointed by the lack of imagination displayed by my fellow programmers here.

It seems to me the client did some research. He may have read somewhere that quality code typically contains about 25% of comments. Obviously he cares/worries about maintenance further down the road. Now, how does he make that concrete in a requirements document that is to be tied to a contract? That is not easy. It may even be impossible. Yet he wants to make sure he will get value for his money so he enumerates some quality indicators.

That does not sound stupid or ridiculous to me at all. The people that wrote the requirements are most likely not programmers. They may have had a bad experience with an earlier project. Their maintenance guys are complaining: "None of this shit is documented!". It is ringing in the ears as they write new requirements for the next project.

If you are serious about documenting your code and about providing context for the maintenance gang, this requirement will be fulfilled automatically. So don't be a pussy about it!

In the end, be it 21% or 29%, no one will care. The client will have your stuff reviewed by some independent developer and he'd better understand what you did.

Answer 12

I have met many programmers who don't understand how people exist that don't currently work on this project.

For them everything that they know, IS known by everyone.

If someone does not know EVERYTHING they currently know, then those people are "idiots" to them.

With this standard you can force people to get into a habbit of writing comments.

They may write useless comments 99% of the time, but sometimes they may actually write down one of the things that "EVERYONE KNOWS", and someone new on the team might actually not spend 16 hours looking for a bug (that someonelse already solved, but then was undone for another reason) that would have been obvious with a comment at that point in the code.

Having comments at lines with unobvious bugs can also help avoid future programmers to completely break a program by accident (especially when the "being broken"-part isn't obvious when doing a quick test).