RE: succinctness = power

["Brent Fulgham" <address@hidden>]

> I agree with Christopher Barber: programmers really, really 
> have got to learn to maintain comments, just the same way they
> have to learn other good programming practices.
> 

In the Civil Engineering discipline, when a project has finished
construction by a contractor from a set of plans, there is a phase
of the project where something called "as-built" drawings are prepared.

An "as-built" drawing represents the actual physical structure at
the time construction finishes.  As with any complex undertaking,
changes must be made on-the-fly during construction due to physical
realities, lack of some particular component or raw material, or even
customer requirement changes.

So, a group of engineers walks through the facility with a set of
plans, and marks them up so they can be modified to reflect what
was actually built, rather than the theoretical design that was
originally produced.

The software engineering discipline needs to learn from the example
of the older engineering traditions, and train itself to perform
a similar "as-built" task with program documentation.

-Brent