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?
Best Answer
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".