Please recommend citations for source code documentation standards

Posted by Aerik on Programmers See other posts from Programmers or by Aerik
Published on 2011-11-17T17:30:49Z Indexed on 2011/11/17 18:07 UTC
Read the original article Hit count: 717

Filed under:

best-practices

|

code-quality

|

source-code

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

© Programmers or respective owner

Related posts about best-practices

Batch Best Practices and Technical Best Practices Updated

as seen on Oracle Blogs - Search for 'Oracle Blogs'
The Batch Best Practices for Oracle Utilities Application Framework based products (Doc Id: 836362.1) and Technical Best Practices for Oracle Utilities Application Framework Based Products (Doc Id: 560367.1) have been updated with updated and new advice for the various versions of the Oracle… >>> More
Partial template specialization of free functions - best practices

as seen on Stack Overflow - Search for 'Stack Overflow'
As most C++ programmers should know, partial template specialization of free functions is disallowed. For example, the following is illegal C++: template <class T, int N> T mul(const T& x) { return x * N; } template <class T> T mul<T, 0>(const T& x) { return T(0); } //… >>> More
Object Oriented PHP Best Practices

as seen on Stack Overflow - Search for 'Stack Overflow'
Say I have a class which represents a person, a variable within that class would be $name. Previously, In my scripts I would create an instance of the object then set the name by just using: $object->name = "x"; However, I was told this was not best practice? That I should have a function set_name()… >>> More
Good place to look for example Database Designs - Best practices

as seen on Stack Overflow - Search for 'Stack Overflow'
I have been given the task to design a database to store a lot of information for our company. Because the task is rather big and contains multiple modules where users should be able to do stuff, I'm worried about designing a good data model for this. I just don't want to end up with a badly designed… >>> More
Notification Email Best Practices--From Server Setup to Programming

as seen on Stack Overflow - Search for 'Stack Overflow'
All, I'm in the process now of building a SaaS tool that allows network admins to generate notification emails to the members of the end-users of our platform (among many many other things). I'm running into a bit of an "out of my expertise" wall, as I know there are a lot of variables involved… >>> More

Related posts about code-quality

Tips on a tool to measure code quality?

as seen on Stack Overflow - Search for 'Stack Overflow'
I'm looking for a tool that can provide code quality metrics. For instance it could report very long functions (spaghetti code) very complex classes (which could contain do-it-all code) ... While we're on the (subjective:-) subject of code quality, what other code metrics would you suggest? I'm… >>> More
Everyday Challenges to Improving Brownfield Code Quality

as seen on Code Project - Search for 'Code Project'
How best does one integrate code quality tools into an active project? >>> More
New Extension - Check ADF Code Quality

as seen on Oracle Technology Network - Search for 'Oracle Technology Network'
New free extension available from check for updates >>> More
Why is code quality not popular?

as seen on Stack Overflow - Search for 'Stack Overflow'
I like my code being in order, i.e. properly formatted, readable, designed, tested, checked for bugs, etc. In fact I am fanatic about it. (Maybe even more than fanatic...) But in my experience actions helping code quality are hardly implemented. (By code quality I mean the quality of the code you… >>> More
Counting Lines of code - quality metircs

as seen on Stack Overflow - Search for 'Stack Overflow'
I'm taking the lines of code for my Java project , the project contains lot of XML files too. Now my question is when calculating lines of code. Do i need to consider XML lines of code as well? Please help >>> More