Soyons en contact

 

Code Documentation

24-04-2017 - 07:2325-04-2017 - 07:10

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


Top
Le Blog Apocryphe utilise des cookies pour sauver vos préférences et RIEN d'autre. Je vous demande de bien vouloir accepter les cookies qui sont positionnés sur mon blog et je vous promets en retour de ne RIEN laisser transparaître de votre parcours de visite, dont d'ailleurs vous me faites l'honneur. Au cas où néanmoins vous n'accepteriez pas d'utiliser les cookies, vous aurez probablement une navigation LÉGÈREMENT dégradée sur le Blog Apocryphe. Bonne visite!X