12

As I boot up Eclipse for C++ with the "Darkest Dark Theme with DevStyle" installed, it spits out quotes--one per day. Yesterday's was:

A bug in the code is worth two in the documentation.

Talk about ambiguous! What does that mean?

A Google search for it (and this one too) shows it is a rather popular quote.

Possible meanings:

  1. (what I'd like it to mean, but what it isn't really saying well in the least): documentation is so important that it takes 2 bugs in the documentation to equal 1 bug in the code, so even if documentation has bugs (meaning: errors, or is out-of-date), it's still better to have the documentation than not to have it.
  2. A single bug fix in the code creates 2 bugs in the documentation unless you update the documentation in 2 places.
    1. Ramifications and implications: don't have documentation--it's too hard to keep up with code changes and bug fixes in the code.
  3. 1 work unit of effort from a developer is enough to fix 1 code bug or 2 documentation bugs.
    1. Ramifications and implications: unknown
  4. 1 work unit of effort from a developer is enough to fix 1 documentation bug or 2 code bugs.
    1. Ramifications and implications: unknown
  5. It's better to have bugs (errors) in the documentation than bugs in the code.
  6. It's better to have bugs in the code than bugs (errors) in the documentation.
Improve this question
2
  • "...these questions aren't educational in any way, because there's no way to learn about the process of discovery. A particular community member, by virtue of their experience in the field, just happens to be able to take the limited information you remembered and fill in enough of the blanks to guess the correct answer... guessing game questions do not meet our goal of making the Internet better." (blog.stackoverflow.com/2012/02/lets-play-the-guessing-game)
    – gnat
    Oct 7, 2020 at 16:08
  • @gnat, ...unlike your very educational remark. What an irony.
    – greenoldman
    Oct 8, 2020 at 17:20

4 Answers 4

Reset to default
9

It appears to be a twist on "A bird in the hand is worth two in the bush" - meaning you should hold on what you have rather than risk losing it for something more. That sentiment can make sense in software engineering, but I don't see how the modification makes sense when you try to parse it as a derivation:

Better to hang on to a bug in the code, than risk losing it to introduce two in the documentation

The original meaning clearly makes no sense. You can twist it in plenty of ways:

  • Bugs in code are about twice as bad as bugs in documentation
  • Better to keep a code bug that is well described in the docs, than to fix it and have outdated docs
  • Bugs in the code take twice the effort to fix compared to bugs in documentation
  • Etc.

But I see no reason to prefer any of these meanings, and without context or attribution I can only insert my own values.

Most matches are on sites relating to "computing humor", along other quotes such as "The definition of an upgrade: Taking old bugs out and putting new bugs in". Given that, plus the open-ended meaning, I think it is simply a funny substitution, and that we shouldn't try to read into it more than that.

Improve this answer
1
5

Let's start from the original:

Taken from the proverb "a bird in the hand is worth two in the bush," which means that having something, even if it is a lesser quantity, is better than taking the chance of losing it in order to attain something else that seems more desirable.

In short, it's better to have one bird than it is to have a chance at catching multiple birds.

The important thing to notice here is that "having a bird" is a positive thing. The main incentive is to have a bird. The former option (having one bird in the hand) is better, because having a bird is good.

You could rephrase the proverb as

Having a bird in the hand is twice as good as having one in the bush

Having a bug, however, is a negative thing. The main incentive is to not have it. This means that the good/bad scales are inverted for this bug-in-the-code proverb.

The former option (having a bug in the code) is worse, because having a bug is bad.

Therefore, the bug-in-the-code proverb roughly translates to

Having a bug in the code is twice as bad as having one in the documentation.

Which is your option #5.

Improve this answer
2

Without further context, I'd take it to mean that bugs are more expensive to fix when they are in code as opposed to in documentation (roughly your point 3.).

This can be expanded - "bugs" in specification/requirements are usually more expensive to fix than bugs in code (as they imply changes to system/integration tests, may affect API or even UI design, etc.) if they are only detected after being implemented.

More generally - a fault in any artefact (document/code/binary) becomes more expensive to fix with every other artefact depending on it. The exact ratio of the increase in cost is hard to measure, but some books on testing strategies claim a factor of 10 for each phase of the software developement lifecycle that passes without the problem being detected.

Depending on the lifecyle model, this could mean
System design > Architecture design > Implementation > User Documentation

Meaning that a fault in system design found during architecture design costs roughly as much as a fault in architecture design found during implementation. If a problem is found once the software is released, fixing issues in documentation is relatively easy, but fixing system design issues may be completely infeasible for economic reasons.

That said, being not a native speaker, I have missed the reference to the proverb the other answers have picked up. Although there is a corresponding proverb in my native language (German), it compares size/quality of the potential vs. actual birds instead of quantity.

Improve this answer
4
  • Can you post your German proverb too?--in both German and with its translation? I'd be interested in seeing it. These types of proverbial themes are frequently found in multiple countries and languages.
    – Gabriel Staples
    Oct 7, 2020 at 15:41
  • By the way, I'm a native English speaker and I didn't pick up on this proverb either. It's not a common saying these days. It comes from Biblical times I think, but isn't a common theme in the Bible either. A more modern version of it is probably, "the grass is always greener on the other side," meaning: "although it appears to be better to leave what you have here to get what you don't have, over there, it usually isn't. Once you arrive over there it will look like where you came from is better. So, stay where you're at." It's kind of similar to the bird one: keep what you have.
    – Gabriel Staples
    Oct 7, 2020 at 15:47
  • Side note: I also really dislike the "grass is greener" quote. It is most often used by people as an excuse not to try something difficult, risky, or which would help them grow at the risk of failing. I was told it many times while leaving a military career behind, saying I wouldn't make it on the outside if I left, and my frustrations would be just as bad on the outside. I left anyway. It was B.S. Now I'm a professional embedded software developer, finally getting to do something which truly uses my abilities rather than having to bury them away. And it is way greener here, for me at least.
    – Gabriel Staples
    Oct 7, 2020 at 15:52
  • 1
    @GabrielStaples this is off-topic for this site, so I'll limit it to a comment instead of adding that to the answer: In German, there is "Besser ein Spatz in der Hand als eine Taube auf dem Dach.", which might be literally translated to "A sparrow in the hand is better than a dove on the roof." See also this german dictonary But if you wish to discuss German proverbs, we should continue this on german.stackexchange.com
    – Hulk
    Oct 7, 2020 at 15:59
1

@Jacob Raihle is spot-on I think when he said:

Most matches are on sites relating to "computing humor", along other quotes such as "The definition of an upgrade: Taking old bugs out and putting new bugs in". Given that, plus the open-ended meaning, I think it is simply a funny substitution, and that we shouldn't try to read into it more than that.

I see that now. Almost every site the quote was found on was intended as computer humor. Ex: this page's title is "Computer Humor".

So, it truly is meant to be a funny substitution for:

A bird in the hand is worth two in the bush.

...with the new, humorous meaning of:

Better to hang on to a bug in the code, than risk losing it to introduce two in the documentation.

How ridiculous. I've gotten some really good and meaningful quotes from that startup splash screen, so I didn't expect to see a ridiculous one like this, and I didn't have the context for where it came from ("A bird in the hand..."). Anyway, that's the meaning.

So, I'll leave you with one of my own:

I understand crossing your fingers is a form of debugging. If it doesn't pass, cross your fingers and try again.

- said nobody ever
(by Gabriel Staples, 25 June 2020)

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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