A well documented SW is something we all like to find, but not always like to generate, probably because it is time consuming and even tedious.
When dealing with non trivial applications, comments are necessary but do not suffice. A separate document with an introduction (goals, alternatives,...) a description (flow charts, state diagrams, communication frames and protocols,...) and a history of modifications will help to the programmer or the programming team in the development process, and also for future revisions. The comments in the source code are a suitable place to include links to the separate document.

Of course, a higher degree of detail in project documentation implies a higher cost, so a balance must be found between quality and cost.

Alfredo del Rio.