Take the 2-minute tour ×

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?

share|improve this question
Take a look at this question, the highest voted answer references Clean Code on the benefits of using comments. And good luck, you're in an extremely tough situation, the "nice to have" mentality on comments doesn't go away easily. –  Yannis Rizos Nov 17 '11 at 17:45
That is a good question / answer, but I'm really looking for succinct online resources that I can give to managers. I am not going to be able to tell the VP of manufacturing to read Clean Code... or even if I read it and quote it, I don't think it will carry the weight I need. I'm looking for citations that I can take to management (who do not have a SW background). –  Aerik Nov 17 '11 at 18:36
Yeap, it was a comment, not an answer. And you should add the above clarifications on what you're looking for in your question. –  Yannis Rizos Nov 17 '11 at 18:39
Good feedback, done, thanks! –  Aerik Nov 17 '11 at 18:47
Why are you making this case to non-software managers? You should be making this case to software/technical managers who should be reading (or have read) Martin's Clean Code and McConnell's Code Complete, analyzing what they read/learn, and then they should be making the case to the business/non-technical managers. Business managers, generally, don't care what the code looks like - they speak in terms of earned value, cost, time, and system quality. The software managers should be taking technical concepts and translating it into these terms, if they can't independently motivate the teams. –  Thomas Owens Nov 17 '11 at 19:06
show 4 more comments

3 Answers

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".

share|improve this answer
getting someone to meet with to explain the code/how it works/what does what is so much more valuable than any amount of comments you could get them to write anyway. definitely try to get someone from their team with knowledge of the code to meet with you every other day or so for an hour or two over a few months depending on size of codebase. –  Ryathal Dec 16 '11 at 21:55
add comment

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!

share|improve this answer
Actually the issue as described in the question is not subjective. The question does not ask if comments are good or bad, or how to convince people either way, the question specifically asks for authoritative citations / references for documentation / comment standards for source code. I think you should revise your answer to highlight the Google C++ Style Guide you link to (and add some excerpts from it), that's actually in the spirit of the question. –  Yannis Rizos Nov 17 '11 at 19:59
@YannisRizos - Thank you, yes, that's exactly right... on further reflection, I think maybe clamontagne is highlighting that this my problem (not the question I asked) is difficult because I'm dealing with opinions here at work. But yes, I tried to phrase my question so that it is not subjective - it is exactly as you have summarized. –  Aerik Nov 17 '11 at 20:05
From what I understood, he is looking for a way to convince management of a process since two teams are of dissimilar mindsets. Standards definitions could help but are readily available en masse on Google. I was more or less catering to his desire to change the minds of management and co-workers. If it is a specification you want, that is something the team should agree upon as a whole. Pointing to one and saying we should use this will only exacerbate the issue, all programmers should be part of defining the processes that define their job. –  clamontagne Nov 17 '11 at 20:12
There are at least a couple of other questions on programmers that discuss the mindset problems regarding comments, so if the question turns to the subjective it might get closed as a duplicate. As for all programmers should be part of defining the processes that define their job I'd add an exception: those that don't comment their code :) –  Yannis Rizos Nov 17 '11 at 20:30
No, I'm not looking for standards, I'm really looking for authoritative citations and references supporting the use of thorough documentation / commenting. It's the citations and references I'm looking for, not the standards. –  Aerik Nov 18 '11 at 0:09
show 3 more comments


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).


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.

share|improve this answer
add comment

Your Answer


