Modern Programming: Object Oriented Programming and Best Practices by Graham Lee

Author:Graham Lee
Language: eng
Format: epub
Publisher: Packt Publishing
Published: 2019-06-26T16:00:00+00:00

Documentation Is More Useful Than You Might Think

A common reason given for not documenting code is that the source code is accurate documentation—http://www.codinghorror.com/blog/2012/04/learn-to-read-the-source-luke.html; that, while documentation can be created with errors in it or can become inaccurate as the software changes, the source is guaranteed to be both an exactly accurate and exactly precise description of what the software does.

If you assume that framework and compiler bugs don't exist, then this idea is correct: the source is complete and exact documentation of the software's behavior. The problem is, it's not always the most appropriate documentation to read.

Sure, source code is entirely accurate, but it's also at the lowest possible level of abstraction. If you've just been brought onto a project and need to get to grips with the unfamiliar software, reading each operation in sequence (once you've even worked out the correct sequence) is not the easiest way to proceed.

Even if you leave this point aside, there are still problems with using source code as your only source of information about the software. It does indeed tell you exactly what the product does. Given a bit of time studying, you can discover how it does it, too. But will the programming language instructions tell you why the software does what it does? Is that weird if statement there to fix a bug reported by a customer? Maybe it's there to work around a problem in the APIs? Maybe the original developer just couldn't work out a different way to solve the problem.

So, good documentation should tell you why the code does what it does, and also let you quickly discover how. It should provide the context at the expense of the details, whereas the source provides all of the details at the expense of making the context hard to discover. In other words, where the source code represents an exact plan to the virtual world you're creating, your documentation should be the tourist's guide—http://www.infoq.com/presentations/The-Frustrated-Architect (This idea was first presented, to my knowledge, by Simon Brown—http://www.codingthearchitecture.com), with maps, recommendations of places to go (and to avoid), and information about world history.

Download

Copyright Disclaimer:
This site does not store any files on its server. We only index and link to content provided by other sites. Please contact the content providers to delete copyright contents if any and email us, we'll remove relevant links or contents immediately.