>>
>>Sometimes I wish a programmer had just written comments on what he/she was trying to do and let me write the code! It would be simpler than debugging.
>>
>> Jay
>
>My first programming job was (too many) years ago using APL. In our documentation training sessions we were given an article entitled 'The Concept of Throwaway Code.' Unfortunately, I can't remember the author. The basic premise was that, in a properly modularized system, a program should document the inputs, outputs, and data transformations. If anything needs fixing or modification it will be cheaper/easier to rewrite the module from scratch rather than try to debug the problem.

Don't your comments in APL end up being longer than the program itself? <g>

I like what you had to say because:

I'd think that having a 'properly modularized system' resolves a lot of issues to begin with! Of course, the 'properly' is the sticky point! To see modules as "bridges" between different levels of abstraction is the most helpful approach for me. Each level speaks it's own, coherent language and doesn't mix its' terms with those of other levels.

Documenting input/output/transformation is the heart of any documentation, especially for structured programming. OO gives its own nuance -- using properties -- which unclutters interfaces, role of the method/class in the wider application model.

Having a standardized interface means that changes in code are usually restricted to the module at hand.

Jay