Re: [boost] Interest in a Behavior Driven Development Framework

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 
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