How can I convince my managers to enforce documentation standards?

Question

I'm trying to convince another group in my company— that's about to hand code off to my group—that they need to provide more documentation in their source code, but they're treating it as a "nice to have".

In my view, it's a necessity. Of course, I also support intuitive naming conventions, but I think I'll have less difficulty getting the original authors to add comments than I would getting them to rename their functions and variables.

I've run a source code analysis tool and it's showing about 10% comment line, but looking at the source code, most of that is coming from entire functions that the author has commented out.

How can I convince my managers to enforce documentation standards on this other team? Have there been studies or work done to prove that code documentation increases profitability or productivity?

Answer 1

If your goal is to somehow convince the other team to sit down and comment-up the code and provide documentation, I think you'll be in for a big disappointment. There's no way a team is going to crack open the code base and start commenting stuff for your team en-masse. Even if they somehow get forced to do it, the value would be dubious at best.

I think a more pragmatic approach is to get the cooperation of some original key developers who can guide your team through the code base and who are willing to come back on an as-needed basis. Call it a "transition phase".

The documentation will have to be written by your team, but the good news is that they'll be vastly more motivated to get it right than a team that has to perform such a task before "throwing it over the wall".

Answer 2

How can I convince my managers to enforce documentation standards on this other team?

In case like that I'd appeal to effort estimation for hand-off. I'd do a preliminary study of available documentation and summarize my findings in a form that is readable for management.

• "1. Source code analysis tool is showing about 10% comment line, but after trial removal of entirely commented functions that value dropped to about 0.5%. 2. Presence of intranet documentation: 1 confluence page with about 1 Kb of text and two sharepoint pages with 20 lines of text. 3. Feature specifications: not found. 4. Issue tracker: studying sample selection of 5 randomly picked issues (#17, #31, #98, #118, #234) has shown these to be completely worthless as a source of project knowledge. 5. VCS: studying sample selection of 5 randomly picked commits (#1017, #1031, #1098, #1118, #1234) has shown these to be completely worthless."

After that I'd present management two efforts estimates to complete hand-off - one for the case if things are as-is and another in case if "another team" provides docs and these docs pass a review from my team and let them choose.

• "Hand off effort for as-is option: about 12 mythical man-months. For a documented-and-passed-review option: 1 month to review plus 1 month for hand-off."

I wouldn't wonder BTW if the management picks the as-is option (been there done that - their brain just sometimes operates on a different frequency if you catch my drift).

Have there been studies or work done to prove that code documentation increases profitability or productivity?

Even if there are such studies they might turn out worthless for you. I mean, even if you somehow will be able to enforce some standard on these guys, they will most likely find a way to quickly hack it through (you mentioned the group has smart guys didn't you?) and leave you with a few hundreds kilobytes of useless garbage that perfectly conforms to your standard whatever it will be.

Answer 3

The problem is that the issue is subjective. You will always have people who think you should write code so clear it doesn't need comments or that any good programmer worth his salt should be able to decipher your algorithms.

If someone believes you don't need comments you are likely not going to convince them. You can only hope to convert the indifferent and get non-believers to follow suit by simply being outnumbered. Which might mean leading by example of taking time to do it yourself and showing the difference/benefit after you have enough to compare and contrast.

One solution might be to promote the adoption of something like doxygen. The benefit being browsable documentation for future team members to browse. This only achieves interface level comments and not implementation level but once you get the ball rolling it's easier to grow from there than with nothing in place.

Otherwise you will just have to build documentation in your favor. Referring to multiple best practices blogs or company blogs. Google says it is important, so it must be!

Ultimately it is you against an established culture and you may not succeed.

Good luck!