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

[Julien Grall <julien@xxxxxxx>]

On 30/05/2022 10:33, Jan Beulich wrote:
> On 30.05.2022 11:27, Julien Grall wrote:
> > 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.
> We all know what "short term" may mean - we may remain in this mode of
> operation for an extended period of time. It'll potentially be quite a
> bit of churn to subsequently adjust all such comments which would
> have accumulated, and - for not being standardized - can't easily be
> grep-ed for.
Well... Scanner will likely point out the issues we deviate from. So you 
we have an easy way to know where the comments need to be adjusted.
> By documenting things in the commit message the state of
> the code base doesn't change, and we'll continue to rely on scanners
> to locate sets of candidates for adjustment or deviation commentary.
The part I am missing how documenting the deviations in the commit 
message help... Can you clarify it?
Cheers,

--
Julien Grall