Re: [PATCH 1/2] docs/misra: introduce rules.rst

[Julien Grall <julien@xxxxxxx>]

Hi,

On 30/05/2022 10:16, Jan Beulich wrote:
> On 30.05.2022 11:12, Julien Grall wrote:
> > On 28/05/2022 00:16, Stefano Stabellini wrote:
> > > """
> > > It is possible that in specific circumstances it is best not to follow a
> > > rule because it is not possible or because the alternative leads to
> > > better code quality. Those cases are called "deviations". They are
> > > permissible as long as they are documented, either as an in-code comment
> > > or as part of the commit message. Other documentation mechanisms are
> > I would drop the "as part of the commit message" because it is a lot
> > more difficult to associate the deviation with a rationale (the code may
> > have been moved and you would need to go through the history).
> But this was added in response to me pointing out that code comments
> aren't standardized yet as to their format. The alternative, as said
> before, would be to come up with a scheme first, before starting to
> mandate playing by certain of the rules (and hence requiring deviations
> to be documented).
I don't think this is necessary short term. It is easy to rework a 
comment after the fact. It is a lot more difficult to go through the 
history and find the rationale.
Documenting the deviation in the commit message also makes a lot more 
difficult to triage issues reported by scanner. With a comment you could 
just read it from the same "page" (scanner will usually provide context).
So overall, I think allowing to document deviations in a commit message 
is a pretty bad move (the more if it is a short term solution).
Cheers,

--
Julien Grall