Gregory's Server@donaldball @mhoye I once had a conversation with a colleague about whether we could enforce this with an automated mechanism. Commits or PRs where code was changed but lacking changes to associated comments would fail. It came down to being able to detect, in any given programming language, which comments were about what code, which seemed like a hard problem.
|
3 comments
  > @jimfl @mhoye whenever practical, use data structures instead of raw code constructs at the documented contract layer Nouns (data structures), verbs (API actions and events), and admonitions (what can go wrong) |
@jimfl @mhoye I have had good success when given the appropriate resources by various combinations of having technical writers flagged via codeowners for e.g. the api contract declarations, having technical writers skim review all changes on a formal release, and providing a clear and actionable grammar style guide so software engineers have a fighting chance to get it right when they write their own.