I am working on a SharePoint 2010 based project which involved three code solutions, one for Visual Web Parts [about 25-30 Visual Web Parts], one for Event Receiver, one for Timer Jobs [2 Timer Jobs]
Client is asking to provide source code documentation, can anyone guide me how can I document my source code... What information should I include when documenting, any samples/examples will be helpful.. Please don't give me Google results, I want experienced people to reply!
I do recommend as well carefully and clever comments within the code (as opposed to a generated source code documentation chm like file) and delivering the complete solution source to the customer (if requested and part of the initial offer).
Added to this, I deliver whenever possible, a Software Architecture Design document and a SharePoint Technical Analysis that will emphasize on the technical & architecture choices (and external / internal systems integration). I find them much more valuable / relevant for the customer than any generated source code documentation (Sandcastle is a good bet if that's required by the customer) since the code can always be refactored / updated afterward (but the core concepts will remain).
In order to help document code while writing it, I'm always installing GhostDoc and ctrl+shift+d on any method / function / property / constructor / class that I'm writing to explain the purpose and receive pre-built parameters and explanations.
So in short, ask your customer the purpose of the source code documentation. If it's for security / penetration tests they won't care about the comments and investigate high risks area (or magic strings left by junior developers), if it's because it's required by their governance / it procedure plan any automatically generated documentation (with well written xml comments) will do the job. If it's to ensure the lifecycle and future upgrade of the solution, well commented code and a solid SAD / Technical Analysis will do the job much better than anything else.
The best source code documentation I've encountered is simply thorough and clear comments in the code itself next to the area it applies to. Comments close to the code are also more likely to be kept in sync with the code over time. Having a block of comments at the top of each class and/or file that explains its purpose and expected usage is very handy too.
Visual Studio already has decent hooks in place that can be used for not only source code documentation but also for generating external documentation via third party tools like Sandcastle though that is generally used for things like API reference for external callers and so forth.
In my experience, any documentation kept outside of the code itself goes from stale to useless in a very short time as it is almost always the last thing on the developer's mind and thus gets forgotten.
