Most discussions about commenting necessarily revolve around how to comment functions/methods/classes, when to comment, how to write code that is so intuitive that it doesn't necessarily require commenting, etc. In my opinion, these discussions miss out a key documentation requirement: describing how everything fits together.
Let's assume the supposed best-case: every single method and class is commented using a language-specific documentation system (I'm thinking of EDoc for Erlang, Javadoc for Java, etc). Who cares? Congratulations: I now know how all your functions work. But what is the system architecture? How do object instances of the different classes hang together to support the functional specifications? What is the sequence of events for various successful and failed transactions?
I suppose what I'm complaining about is the rationale that code commenting can necessarily substitute a solid set of functional specification and design documents. Then again, noone here made this suggestion, so maybe I'm just whining into a black hole. The only open-source project that comes to mind when I think of an astoundingly high quality of documentation is SQLite in the form of "Inside SQLite (2007)" (O'Reilly); unfortunately it's not free.
Let's assume the supposed best-case: every single method and class is commented using a language-specific documentation system (I'm thinking of EDoc for Erlang, Javadoc for Java, etc). Who cares? Congratulations: I now know how all your functions work. But what is the system architecture? How do object instances of the different classes hang together to support the functional specifications? What is the sequence of events for various successful and failed transactions?
I suppose what I'm complaining about is the rationale that code commenting can necessarily substitute a solid set of functional specification and design documents. Then again, noone here made this suggestion, so maybe I'm just whining into a black hole. The only open-source project that comes to mind when I think of an astoundingly high quality of documentation is SQLite in the form of "Inside SQLite (2007)" (O'Reilly); unfortunately it's not free.