Great questions. You have spotted the main differences between community code projects and managed/professional code projects.
Ideally, the requirements, primary sources, and any deviant behavior from the primary sources should be documented in the source code base. However, this depends upon the diligence and understanding of the coders in an open source community model. The best answer is "coders try to document what seems important at the time, unless it appears obvious [to them]". However, one of the main problems with "completing" the source documentation in this way is that most of the deviant behaviors are found experimentally. It is then difficult for the code maintainer to document the deviant (undocumented) behavior, only that the patch "works". And thus "lore" is born. We could potentially solve some of the source code quality with a source code template, but practically, coders copy an existing source code file that is similar and modify it. So we'd really need to upgrade the existing modules to the "source code standard" before being able to ensure that future coders do it the right way. Or else have the project introduce the additional management overhead of explicitly defined coding standards, checklists, and gatekeeper code reviews. :-) Both are a lot of work, so in community projects source code improvement tends to happen with slow code evolution. Volunteers for source code improvement are always welcome. Hardware/software interactions are never ending issues in hardware simulation, primary sources, and OS use of the real and simulated hardware. Bob Supnik has an excellent series of papers discussing many of these discovered hardware/software interaction issues on the SIMH papers page. http://simh.trailing-edge.com/papers.html Dave From: Simh [mailto:simh-boun...@trailing-edge.com] On Behalf Of Armistead, Jason BIS Sent: Tuesday, January 05, 2016 10:13 AM To: simh@trailing-edge.com Subject: EXT :[Simh] The minutiae of hardware/software interactions affecting SIMH On the topic of Configuring DMC11 Devices, while discussing wait delays Mark Pizzolato recently wrote: > Sounds reasonable. I've got to see if I can find the reason the delay was > initially added and make sure a change like this is compatible. What is the "SIMH strategy" for documenting such requirements ? i.e. where does this behavior get called out in the source code (or elsewhere) in a way that will allow future generations of SIMH users and maintainers to understand "why things are the way they are" or "why things need to be the way they are" ? There is one reference to the DDCMP protocol manual in the source of pdp11_dmc.c, but that's about it. Should references to other documents be added ? Reconstructing and understanding history is easy when people familiar with the subject matter (especially those who lived it, in this case, at DEC) are still around to ask, but gets progressively harder as years go by without leaving a good trail of "breadcrumbs" for others to follow. PS: I am constantly amazed at the sheer volume of knowledge and resourcefulness that contributors to this list have, which is one of the reasons I'd love to see as much of it preserved directly in the SIMH code base !!! Jason
_______________________________________________ Simh mailing list Simh@trailing-edge.com http://mailman.trailing-edge.com/mailman/listinfo/simh
