96

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 ?

closed as too broad by Robert Harvey, gnat, Greg Burghardt, Thomas Owens Mar 7 '18 at 1:26

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 162
    That's ridiculous. However, if that's what the client wants and the client is paying you good money to get it, then that's what you give him. – Robert Harvey Mar 5 '18 at 22:01
  • 20
    25% of lines (meaning you never put a comment on the same line as the code) or 25% of bytes? – RonJohn Mar 6 '18 at 2:54
  • 6
    essentially same rant as in My boss wants a narrated line-by-line English explanation of our code – gnat Mar 6 '18 at 4:46
  • 10
    Better be carefull here. Usually there is a reason behind this kind of expectation... If you tell your customer those comments are useless, he/she may still want 25% comments (with whatever reason they have) but now WITHOUT the ones you name as useless... you may find yourself in more trouble .... Sometimes customer arguments are so far fetched that it will baffle you... Just speaking from experience – user1841243 Mar 6 '18 at 8:58
  • 19
    This is an object lesson in a rule that you will have ample opportunity to observe in your career: the thing that you measure is the thing that you get. You've been given a metric for comments, and therefore comments are the thing that you'll get. A more sensible customer would give you metrics for performance, correctness, robustness and cost, and then you'd get those things. But you don't have a sensible client. – Eric Lippert Mar 6 '18 at 15:00

12 Answers 12

114

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  • 3
    Nice positive take on the question :-) – cmaster Mar 6 '18 at 14:04
  • 9
    @ThorstenS. The company I work for does a supermajority of its work for the defense industry. Might want to get your psychic powers checked. Also, I never said "do not interpret their wishes how they wrote it": I would treat "25% comments" as a serious but incidental request -- the real request is "a large body of technical writing", and 25% is just an indication about the effort level they expect to go into that body, probably chosen essentially arbitrarily, but nevertheless a target that you should not miss. – Daniel Wagner Mar 6 '18 at 14:32
  • 12
    If I was hiring a programmer, Mr. Daniel Wagner is the kind of guy I would want to hire. – Joe Gayetty Mar 6 '18 at 14:56
  • 5
    This is a great answer as it seeks to identify and address the intent of the request as opposed to the letter of the request. IMO This is the difference between a developer and someone who just writes code. – Justin Ohms Mar 6 '18 at 18:12
  • 6
    It would also be good to make it explicit that these comments will increase the maintenance cost. Once created, they must be constantly updated, or they are a waste of time and money. (Waiting until tomorrow to +1 so you actually get the rep. ;) You deserve it.) – jpmc26 Mar 6 '18 at 20:17
83

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).

  • 7
    If the customer is king, it just goes to show how inefficient such customer kingships are! – Steve Mar 6 '18 at 1:44
  • 82
    "The customer is king. So as contractor you shall meet whatever the client has defined as quality standard. Or you risk to be out." The reverse has been my experience. Those who give their customers what they think they want and not what they actually need don't survive very long. In fact, I only reserve this form of abuse for real problem clients -- and a second dose has never been needed. – David Schwartz Mar 6 '18 at 4:34
  • 6
    @DavidSchwartz yes, certainly. Sometimes customers think they need something but really need another. Up to the consultant or the developper to convince, and 2/3rd of my answer is exactly about this. But it all depends on the contractual context and the level of trust between the provider and the client. So the rule of customer is king has to be reminded (in fact I experienced several times with customers, that after a long debate about optimal solution, I raised this sentence and that triggered a sudden change of attitude and careful reconsideration of argumnts;-) ). – Christophe Mar 6 '18 at 8:54
  • 7
    "Accuracy issue: if changes are done in the code, they must be done in the comments, or the comments might become useless." I'd say it's even worse than just useless. A comment that is out of date might turn into a bug (or someone reverting it because they think it's a bug) real quick when you expect that to be the source of truth and trust it. – Hamatti Mar 6 '18 at 14:35
  • 11
    @Hamatti Indeed. I once spent a considerable amount of time deciphering the original intent behind a line that read, i++; // count down – TKK Mar 6 '18 at 18:23
18

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.

  • 13
    Self-explaining code is a lovely principle. Sadly it doesn't work so well in the real world though. Interfaces and complex internal processes need to be documented, and simply choosing nice names is not good enough. What units are those values? Scaling factors? Sample rates? When is it safe to call that method, and when isn't it? What exceptions get thrown for what conditions? And so on, and so on. This is what makes your code maintainable. The real world has complexity which a code snippet will never represent, and that's why you need this documented properly. – Graham Mar 6 '18 at 15:11
  • 2
    @Graham Yeah, comments aren't totally unavoidable. But, comments are like code: the more you make, the more needs to be maintained. Staying concise helps I believe. – Robert Dundon Mar 6 '18 at 18:34
  • I don't want to say that somments are completely useless, but comments exactly like the name of the function or the variable aren't useful. The short bit of code should show that it's possible without comments and should not enforce a comment-free environment. If you want to show what exceptions get thrown or describe the fuctionality further, you could use the summary tag for functions. If you want to signal dependencies, model the needed object as input parameter etc.. There is no perfect way to do everthing, just get the best of both worlds – Chrᴉz Mar 7 '18 at 11:32
  • @Chriz Absolutely, I agree. If comments don't add information, leave them out. But as I said on another reply, the percentage is really just a code smell test. You justify it, the auditor checks it, everyone moves on. The concern is someone who thinks their code truly is self-explaining, and hasn't thought about all those kind of things. – Graham Mar 7 '18 at 13:54
12

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.

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...

5

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.

  • That's a nice one as well +1. I don't know if there can be a good goal expressed in terms of comment rate, but maybe many of us reach this ''goal'n in a useful way, without knowing... I recently found back an old piece of code that I wrote in the 80's at the beginning of my career, with an innovative high performance algorithm in it: it has only 10% of comments, but retroactively, I wish I had put sole more in it ;-) – Christophe Mar 7 '18 at 6:53
4

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.

3

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.

2

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.

  • Yes. Arbitrary rules result in people modifying their behavior to take advantage of the rule. This is the problem with bureaucracy. It baffles me how people can make up a rule and not consider that the people who are affected by the rule may take it into consideration when deciding what to do. Then they make more rules to plug the loopholes, and more rules to plug the loopholes created by the loopholes, etc. – Jay Mar 6 '18 at 16:32
2

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.

2

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.

  • 1
    The question definitively proves that expressing a comment rate as goal will backfire. It would have been more effective for the client to have as goal goal that code must be understandable by another developer (in the team? From outside? With what background knowledge and skills?) and give the 25% as a (flexible) guideline. Expressing it this way would have been better understood by the contractors, and encouraged better alternatives, such as clean code. – Christophe Mar 7 '18 at 7:10
0

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).

  • 3
    The problem with letting 10000 monkeys bang on typewriters isn't that they don't ever write something valuable, but that those vanishingly rare gems are hard to find in the heap of garbage. – Deduplicator Mar 7 '18 at 1:44

Not the answer you're looking for? Browse other questions tagged or ask your own question.