Joel de Guzman wrote:
But why would a layperson have to read pseudo-english embedded in arcane C++ when she can read the documentation? IMO, (sorry Dean) all this hoopla is just an elaborate excuse not to write proper detailed documentation. IMO, programs that end up overly complex and rife with potential error stems from the lack of documentation and design discipline. Code goes haywire and get into a tangled mess, and hence become unreadable in the process. It does not start from unreadable code, it starts from lack of, inadequate, or improper documentation.
Two reasons come to mind: (1) often writing "proper detailed documentation" isn't appropriate, and (2) translation error. Writing separate documentation isn't always appropriate or desired. For instance, in an XP scenario, you only write that documentation that will be immediately useful: users' guides and the like; it would be an undesired weight on the development effort to write internal code construction documentation. You count on the code construction and the unit tests to directly communicate the notions to follow on programmers. Further, writing documentation of the algorithms at a detailed enough level to understand what the details of the design was may have a cost at least as high as writing the code itself. At the very least, the code itself should communicate to the next reader, be it layperson or programmer, what the design was; otherwise, we could go back to 4 letter variable names. Since you go that far, why not have the discipline to write readable code, readable at least at some level by the layperson? Why write it twice: once in code and once in natural language? Perhaps I've not correctly interpreted what you mean by "proper detailed documentation." IMHO, proper detailed documentation is simply readable code. Second, every time you translate between the spec and the code, you introduce the possibility of translation error. It's bad enough when under classic lifecycles, you might translate from spec to analysis models to design documents to code to test scripts, then you add documentation to describe what you did. It may not be reasonably as Rene pointed out to do this directly from spec to code, but from reconciling from code to spec ought to be possible. At some degree, having the code clearly reflect the algorithms involved, such that a layperson can assess what product does, allows these translation layers to be reduced. Finally, please note that I would not advocate writing code such that C++ operators and the like are rewritten into pseudo-English (or whichever). For instance, the tertiary operation is what it is and this I intend to solve by explaining to a lay person what it means rather than going through goofy gyrations just to make it look like natural language. Most people would get the gist that "==" means whether something is equal to something else. However, writing some dense formula that depends on operation precedence is not as readable as breaking a formula down with clear variables or using explicit parentheses to help a reader follow the logic and reason for formula. Regards, Richard