I wasn't referring to comments, although the reasons for writing prefatory comments before the code are clear, but to external documentation. Not so much at the beginning, but once I had TSO FORMAT as an alternative to ATS, and even more so once I had SCRIPT, I would do user documentation first, then module comments, and finally code. I miss the DCF based software.
-- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List [[email protected]] on behalf of Jeremy Nicoll [[email protected]] Sent: Wednesday, June 16, 2021 7:25 AM To: [email protected] Subject: Re: Coding for the future On Wed, 16 Jun 2021, at 09:23, Seymour J Metz wrote: > I developed the habit of writing documentation first, and changing the > documentation before changing the code. It has served me well. Likewise; I document what the parameters to routines will be and what will be returned for both normal calls and errors. I illustrate them with what I think would be sample values & the corresponding results. Later on, when I write code, I usually use the same samples (or parts of them) in the comments, showing how the code manipulates the values. In any block of code that does something complicated I will start off with a comment block describing the problem, the approach I'm taking, the data structures I'm using (& sometimes why I chose those and what else I considered) and describe how that code would act on particular inputs etc. Then in the code I try to comment showing the likely contents of variables for (if there's space) several sample values - typically two boundary conditions and a middle-of-the-range value. ALL my code these days is written only for my use. I've concentration problems (with my long-running illness) and this means that more than ever I need the help that decent documentation gives me when I revisit my own code. The same lack of concentration unfortunately means that getting started on writing new stuff is much harder because I have to to a lot of the abstract design thought and documentation first. On the other hand when I finally write code a lot of the hard work has already been done. -- Jeremy Nicoll - my opinions are my own. ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
