Worst documentation I've seen?

Our "Coding Standards" 20+ page document. The team who put it together got so detailed, there wasn't much 'wiggle room' for natural deviations in a developer's coding style. For example, a section devoted to no abbreviations. So if you had a variable 'invoiceId', they complained you violated 'standards', even though 'invoiceId' matched a field name in a database table. Using Dapper or another ORM that relied on the 1:1 name match? Nope, you were still forced to inject your own mappers so the code didn't violate standards.

As you can probably guess, such a long, detailed document would have contradictions. I pointed out one of the contradictions. Example:

Page 5: Section B, sub-section B-5, paragraph 3 : "To minimize network traffic, when querying the database, request all the data necessary for the application."
Page 8: Section K, sub-section K-2, paragraph 4 : "For maximum performance, when querying the database, request only the most minimum amount of data necessary for the application ."

In a review I pointed out this contradiction (there were several more)
Me: "If we satisfy A, one could say the code is in violation of B. Which is it?"
<Pointy-Hair-Boss throws his pencil on the table>
PHB: "WHAT IS YOUR PROBLEM WITH STANDARDS! It couldn't be more clear! We are a company of standards because without standards <blah blah..straw man argument..blah blah>"
<deciding not to die on that hill, I move on>
Me: "On page 12, paragraph 9 code is in violation if a method has more than 3 parameters. That seems a little restrictive given our interaction with 3rd party products."
PHB: "There you go again. As stated in the document, ALL code used by the company will comply to our standards. What part of 'ALL' do you not understand?"

Was he bluffing about requiring 3rd party vendors complying with our standards? Heck no. That's a story for another day.

  • 3
    Ask whether the boss understand the documentation. The quickest way to get fire :)
  • 2
    That's brutal.

    Yeah probably not the hill to die on, but if possible I'd be all "Hey let's see this IN CODE." "Here's a network request demanding everything that violates A, here's one demanding lots of little things over time violating B... what is the right choice that doesn't violate anything and follows all the rules?"

    Granted... maybe better to just move on.

    Personally I think a lot of "policy" is really just filler for bad leadership....
  • 4

    > So it should be what? Invoice Identification?

    The team attempted to push standards to the DBAs, so field InvoiceID should have been InvoiceNumber.

    The DBA manager was kind of an asshole (in a good way), and told him he wasn't adhering to those standards.

    That day I heard:

    D: "We adhere to our standards, not yours. If that's a problem, lets go talk to vp-John. Heck, president-Bob is next door. I'd bet he love to get in on this conversation."

    PHB: "Whatever. Why do you always got to be a dick?"

    D: "Not trying to be, just letting you know where the line is and to not cross it."

    I miss 'D'. He displayed the same attitude towards a VP...once. You can guess what happened.
  • 1
    @rutee07 Making standards and rules are easy. Folks feel like they're solving problems and etc oh so easily ... they're not, but like an addictive video game that makes pretty colors ... they like those easy good feels.
  • 1
    @PaperTrail but... InvoiceId is so much better. It's more specific (you know the number is an identifier, not a count or sum or something else), shorter, and absolutely every adult in the world knows what "ID" means.

    God I'd hate to see the rest of that standards doc.
  • 1

    > God I'd hate to see the rest of that standards doc

    There was a table for commonly "mis-used" field names.

    PONum should be PurchaseOrderNumber

    InvoiceID shouldbe InvoiceNumber

    ProductID should be ProductNumber

    .. many others.

    The standards doc was mostly used as a weapon to pick on developers the standards team/department mgr didn't like.

    I can't count how many times I've been 'called to the office' because of standards violations.

    Some were valid, wasn't the ideal unit test writer, but the code I wrote 5 years ago?...stop...just stop.
  • 6
    I wrote a 70+ page "code standards" doc once for a client that had really bad developers. It was less a standards doc and more a "how to do your job" paint by numbers kit.
  • 0
    "Don't adhere to our way to strict standards? Off to gulag."
  • 0
    Switch to Python, use namedtuple to inject several named parameters as a single object to the function. ;)

    Or just use an object in any language for that. One object is one parameter... But then you probably have a more-than-3-parameter constructor.
  • 0
    @SortOfTested I would like to read that
Add Comment