CodeSOD: Documentation on Your Contract
Josh's company hired a contracting firm to develop an application. This project was initially specced for just a few months of effort, but requirements changed, scope changed, members of the development team changed jobs, new ones needed to be on-boarded. It stretched on for years.
Even through all those changes, though, each new developer on the project followed the same coding standards and architectural principles as the original developers. Unfortunately, those standards were "meh, whatever, it compiled, right?"
So, no, there weren't any tests. No, the code was not particularly readable or maintainable. No, there definitely weren't any comments, at least if you ignore the lines of code that were commented out in big blocks because someone didn't trust source control.
But once the project was finished, the code was given back to Josh's team. "There you are," management said. "You support this now."
Josh and the rest of his team had objections to this. Nothing about the code met their own internal standards for quality, and certainly it wasn't up to the standards specified in the contract.
"Well, yes," management replied, "but we've exhausted the budget."
"Right, but they didn't deliver what the contract was for," the IT team replied.
"Well, yes, but it's a little late to bring that up."
"That's literally your job. We'd fire a developer who handed us this code."
Eventually, management caved on documentation. Things like "code quality" and "robust testing" weren't clearly specified in the contract, and there was too much wiggle room to say, "We robustly tested it, you didn't say automated tests." But documentation was listed in the deliverables, and was quite clearly absent. So management pushed back: "We need documentation." The contractor pushed back in turn: "We need money."
Eventually, Josh's company had to spend more money to get the documentation added to the final product. It was not a trivial sum, as it was a large piece of software, and would take a large number of billable hours to fully document.
This was the result:
/** * Program represents a Program and its attributes. */
or
/*** Customer represents a Customer and its attributes.*/
[Advertisement] ProGet's got you covered with security and access controls on your NuGet feeds. Learn more.