I'm trying to convince another group in my company that they need to provide more documentation in their source code (they want to hand off the code to my group) but they're treating it as a "nice to have". In my view, it's a necessity. (Of course, I also support intuitive function and variable names, etc - 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... and, IMHO, sometimes you need more than just function and variable names to understand how the code is supposed to work - this question is not about that).

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

Can anyone provide some authoritative citations / references supporting documentation / comment standards for source code? I'm not looking for the standards, I'm looking for an authoritative business case supporting thorough documentation / commenting. (In case it matters, we're a C# house, with a little Matlab thrown in).

This question is really looking for citations / references that would be useful to take to non-software managers to support the request, ideally with data about time necessary for new programmers to come up to speed, etc.

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?

I'm trying to convince another group in my company that they need to provide more documentation in their source code (they want to hand off the code to my group) but they're treating it as a "nice to have". In my view, it's a necessity. (Of course, I also support intuitive function and variable names, etc - 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... and, IMHO, sometimes you need more than just function and variable names to understand how the code is supposed to work - this question is not about that).

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

Can anyone provide some authoritative citations / references for documentation / comment standards for source code? (In case it matters, we're a C# house, with a little Matlab thrown in).

This question is really looking for citations / references that would be useful to take to non-software managers to support the request, ideally with data about time necessary for new programmers to come up to speed, etc.

I'm trying to convince another group in my company that they need to provide more documentation in their source code (they want to hand off the code to my group) but they're treating it as a "nice to have". In my view, it's a necessity. (Of course, I also support intuitive function and variable names, etc - 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... and, IMHO, sometimes you need more than just function and variable names to understand how the code is supposed to work - this question is not about that).

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

Can anyone provide some authoritative citations / references supporting documentation / comment standards for source code? I'm not looking for the standards, I'm looking for an authoritative business case supporting thorough documentation / commenting. (In case it matters, we're a C# house, with a little Matlab thrown in).

This question is really looking for citations / references that would be useful to take to non-software managers to support the request, ideally with data about time necessary for new programmers to come up to speed, etc.

I'm trying to convince another group in my company that they need to provide more documentation in their source code (they want to hand off the code to my group) but they're treating it as a "nice to have". In my view, it's a necessity.

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

Can anyone provide some authoritative citations / references for documentation / comment standards for source code? (In case it matters, we're a C# house, with a little Matlab thrown in).

I'm trying to convince another group in my company that they need to provide more documentation in their source code (they want to hand off the code to my group) but they're treating it as a "nice to have". In my view, it's a necessity. (Of course, I also support intuitive function and variable names, etc - 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... and, IMHO, sometimes you need more than just function and variable names to understand how the code is supposed to work - this question is not about that).

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

Can anyone provide some authoritative citations / references for documentation / comment standards for source code? (In case it matters, we're a C# house, with a little Matlab thrown in).

This question is really looking for citations / references that would be useful to take to non-software managers to support the request, ideally with data about time necessary for new programmers to come up to speed, etc.