Code Documentation

The further removed from the source code your API documentation is, the more likely it is to become outdated or inaccurate over time. A good strategy to mitigate this is to embed the documentation directly into the code and then use a tool to extract it. — Bill Sourour in . Putting comments in code: the good, the bad, and the ugly

Actually, code is the only place where documentation should be! Not only because this lowers the risks of having doc and code out of sync but more importantly because the code is the only place developers go when they are looking to fix a problem: only if they don't find the cause of a problem in the code will they start looking for written documentation, which they usually quickly abandon — most likely because it is outdated and doesn't help them either — to return to the code anyway. A written documentation should be nothing else but a nicer form of the doc that is in the code. The time has come for having smarter code editors that would allow external documents to show up in the code (.xls, .doc, .ppt, .bad, images, etc.) while being excluded from code compilation or code execution.