WIP: Code comments standard

[deanwhitehouseHO]

Is this pull request a content or a code change? (Please fill in the relevant section and delete the other)

Code change

I can confirm:

Accessibility considerations

• [ ] Please review the accessibility checks for layout changes.

• [x] This change will not change layouts, page structures or anything else that might impact accessibility

or

• [ ] This change might impact accessibility, automated aXe tests cover the impact

or

• [ ] This change might impact accessibility and is not covered by automated aXe tests - manual testing has been performed (If the change might impact accessibility then please add some further information here)

Content change

• [x] Please review the accessibility checks for content changes.

I can confirm:

• [x] Content does not include any code or configuration changes (excluding frontmatter information)
• [x] Content meets the content standards e.g. Writing a principle and Writing a standard
• [x] Content is suitable to open source, i.e.:
  • Content does not relate to unreleased gov policy
  • Content does not refer to anti-fraud mechanisms
  • Content does not include sensitive business logic
• [x] Last updated date for content is correct

[edhamiltonHO]

Looks like a good candidate for review with the Software Design guild 😃

Could you please create and link an issue for this proposed standard

Also, tests on valid links are failing. Rebase should fix those failures that have not already been addressed in your second commit

[deanwhitehouseHO]

Looks like a good candidate for review with the Software Design guild 😃

Could you please create and link an issue for this proposed standard

Also, tests on valid links are failing. Rebase should fix those failures that have not already been addressed in your second commit

@edhamiltonHO updated with a linked issue and resolved the errors in build :)

[robertdeniszczyc2]

Apologies I've not been to the Software Design guild so conscious this question might have already been asked, but I noticed this is tagged as Ways of Working too so I have an interest.

Reading through the draft for this, I wondered whether this is a Standard or more of a Pattern. We already have Patterns covering docs-as-code (https://engineering.homeoffice.gov.uk/patterns/docs-as-code/) and writing effective documentation (https://engineering.homeoffice.gov.uk/patterns/write-effective-documentation/) and I see this as an extension particularly of the effective documentation Pattern. I see the Standards more for something non-negotiable and concrete like "encrypt data", but this feels more like recommendations of how to employ code comments.

Happy to be challenged on this,

Thanks, Rob

[aaronrussellHO]

Apologies I've not been to the Software Design guild so conscious this question might have already been asked, but I noticed this is tagged as Ways of Working too so I have an interest.

Reading through the draft for this, I wondered whether this is a Standard or more of a Pattern. We already have Patterns covering docs-as-code (https://engineering.homeoffice.gov.uk/patterns/docs-as-code/) and writing effective documentation (https://engineering.homeoffice.gov.uk/patterns/write-effective-documentation/) and I see this as an extension particularly of the effective documentation Pattern. I see the Standards more for something non-negotiable and concrete like "encrypt data", but this feels more like recommendations of how to employ code comments.

Happy to be challenged on this,

Thanks, Rob

We all agreed in the SD guild meeting to move some of the points into existing pattern/create a new pattern.