Boost logo

Boost :

From: Richard Newman (richard_at_[hidden])
Date: 2006-09-15 12:52:21

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

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.


Boost list run by bdawes at, gregod at, cpdaniel at, john at