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
