best-practice-and-impact / qa-of-code-guidance

Guidance for quality assurance of code for civil service researchers and analysts.
https://best-practice-and-impact.github.io/qa-of-code-guidance
Other
75 stars 18 forks source link

Add why items on the quality review checklist are needed #181

Open sarahcollyer opened 5 months ago

sarahcollyer commented 5 months ago

The quality review checklists don't explain why each item is needed. We should consider adding a column to provide clear explanations of how the item contributes to quality code and why it is important to review it.

RichardP-tt commented 4 months ago

There do seem to be explanations in your guidance sections for each 'topic' heading, e.g. Modular Code, but they are not easily found from the checklist. Maybe a simple fix is links in the checklist?, e.g. Modular Code section of the checklist could link here https://best-practice-and-impact.github.io/qa-of-code-guidance/modular_code.html

It would be great if the 'why' were expressed as risks, then there could be a Risk Rating column, and an Action column (the risk control action) - we find both to be useful additions. We also add a column for 'Evidence/comments' where the assurer can put links to the evidence for the decisions/ratings (e.g. code snippet with line number) and also rationale if needed.