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
74 stars 18 forks source link

Issue on page /checklist_moderate.html. Explicit, rather than implicit names #165

Open JamesABaker opened 11 months ago

JamesABaker commented 11 months ago

We are having an issue interpreting the following line in the moderate checklist. We are seeking guidance on interpreting this.

- [ ] Names used in the code are explicit, rather than implicit.

How should we interpret this line? It feels like there are two interpretations.

  1. Firstly is that the variable names are precisely named like agriculture_data_parser rather than vaguely named parser or p.
    • I am not quite sure how this is different to - [ ] Names used in the code are informative and concise.
  2. Another interpretation is that we are talking about explicit and implicit variables or operands, but I don't see how the name would be part of this.

Any guidance would be greatly appreciated 😊

emountier commented 10 months ago

I'm also looking for guidance on this 😊