Design documentation can be valuable.  Sports, play-by-play commentary 
of what the code is doing, not so much.

On 4/16/17 11:37 , tim Rowledge wrote:
> This was pretty interesting stuff. At first I was a bit worried that he was going to only concentrate on dead languages written in tedious fixed-font string editors with columns and …blech.
>
> His explanation of why you don’t want to make getters and setters in general and especially not off the bat and very especially not by default was very nicely done.
>
> I disagree with a lot about what he said about commenting though. Writing good clear code is so obviously important that we needn’t belabour the point. Where I object is the idea that having clear code is enough; the code can (when well written etc etc) tell you what it actually does BUT it cannot tell you what it was meant to do, how it is supposed to interact with other code, whether the current state of the code is considered complete (ie does it meet the original spec?) and so on. The code is what *is*. It provides no information about what was *supposed* to be.
>
> Ted Nelson once commented that programming ought to be part of the school of film and theatre (I think. I can’t provide a citation. Deal with it.) and I’m somewhat inclined to agree, because software is a story. You need a script, motivation, interactions, dialogue and you sure as hell need directors and producers.
>
> tim
> --
> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
> Strange OpCodes: CEQ: Corrupt and Erase Queue
>
>
>