I've read contradicting essays of what the documentation must look like. Some suggest more documentation is good, when you hire a new chap. Some suggest less documentation is always better, as your code should be explanatory enough. If not, you've hired the wrong coder or written bad code.<p>So, how should one document:-
1. Code
2. DB design(Is just an ER diagram enough?)
3. API end points.<p>I'm the only one involved in coding and setting the "standards" when it comes to these things, so was wondering what do others follow here.
I think the answer has to be, "it depends on the project".<p>I've read numerous gripes against commenting code, because it's possible to change the code but not the comment, rendering the comment inaccurate. I reckon that's true, and it's certainly a reason to be as conservative as possible in commenting code. But how conservative is that? None at all?<p>I have at sundry times worked on a codebase that simulates a fairly complex avionics subsystem. It's a hundred subprojects of C++ code, almost entirely undocumented. I imagine it all makes sense to the original author, and it might make sense to someone intimately familiar with every facet of the avionics subsystem that it simulates.<p>The function names <i>look</i> self-documenting; the variable names <i>look</i> self-documenting. But the problem is, you'd have to read <i>and thoroughly understand</i> something like a thousand pages of dry ARINC specifications before these self-documenting function names would reveal themselves for what they are.<p>I have a hard time believing that the best way to document this software project is "not at all".<p>In general, I personally like to draft a design document up front that explains the intentions of the project and rationale for choices made, and for why the project needs to exist in the first place. Some good hints at:<p><a href="http://philip.greenspun.com/software/design-review" rel="nofollow">http://philip.greenspun.com/software/design-review</a><p>The larger and more complicated the project, the more in-depth the design documentation should be. Even for quick weekend web app hacks, spending a half-hour drafting a design document can be beneficial.