Potential ways to improve the generated code and documentation

[smiths]

As an outcome of reviewing the generated artifacts (code, README, Makefile) for Projectile several issues were created for improving Projectile and the other examples (#3206, #3207, #3208, #3209, #3210, #3211, #3212, #3213, #3214, #3217, #3218, #3219, #3220, #3221, and #3222). Although not ready to become issues, some additional observations came up during the review. These additional observations are recorded here, so that they can be discussed and potentially worked into the artifact generation in the future.

• improve the traceability between the SRS and the code. For instance, the code implements the calculations for equations that appear in the SRS. The code could include a comment that points back to the source of the equation in the SRS. The comments could be part of a header at the beginning of the file, or located with the equation. The idea is that someone that is interested in the origin of the equation can trace back to the details on the equation, potentially including its derivation
• a related idea would be to generate the relevant equations themselves as LaTeX equations as comments in the code. We could then use the idea from literate programming where someone that wishes to verify the code to verify for themselves that the mathematical equation and the code implementation match.
• include comments in the code that refer back to the relevant named theories (or data definitions, or instance models). It might even be possible to generate a hyperlink that directly takes someone to the relevant part of the documentation.
• generate a mapping between SRS symbols and code names. Although it is obvious in many cases, the mapping between the SRS symbol and the name in the code is useful information for someone trying to understand the code. Since we already automate the generation (I believe) of the code names from the SRS variable names, I'm hoping this would be an easy addition.
• provide a design option that puts the constants together in their own file. For the Projectile example this would be a file for the constants G and $\epsilon$.
• close the gap between requirements and design. Decisions are made to refine the theories in the SRS into code, but we currently handle those decisions in an ad hoc way. For instance, the code for Projectile uses a test of relative error to judge whether the projectile's landing position matches the target position. This is a decision that isn't in the SRS, but it needs to be made to implement the code.