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

[Bertrand Marquis <Bertrand.Marquis@xxxxxxx>]

Hi,

> On 30 May 2022, at 11:21, George Dunlap <george.dunlap@xxxxxxxxxx> wrote:
> 
> 
> 
>> On 30 May 2022, at 10:55, Jan Beulich <jbeulich@xxxxxxxx> wrote:
>> 
>> On 30.05.2022 11:41, Julien Grall wrote:
>>> 
>>> 
>>> 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?
>> 
>> I understood Stefano for this to merely be for the purpose of justifying
>> the deviation (preempting review comments).
> 
> Right, so at a very minimum, if we say “This is a rule now”, and a submitter 
> wants a deviation from that rule, then the reviewer needs to know the 
> justification for the deviation.  The commit message is the obvious place for 
> that.

Agree

> 
> Obviously something *else* we might want is a more convenient way to keep 
> that rationale for the future, when we start to officially document 
> deviations.  Given that the scanner will point out all the places where 
> deviations happen, I don’t think an unstructured comment with an informal 
> summary of the justification would be a problem — it seems like it would be a 
> lot easier, when we start to officially document deviations, to transform 
> comments in the existing codebase, than to search through the mailing lists 
> and/or git commit history to find the rationale (or try to work out unaided 
> what the intent was).  But I don’t have strong opinions on the matter.

Maybe agreeing on a simple tag to start that can later be improved (Luca 
Fancellu on my side will start working on that with the FuSa SIG and Eclair 
next month).

So I would suggest:

/**
 * MISRA_DEV: Rule ID
 * xxxxx justification
 *
 */

Whenever we will have defined the final way, we will replace those entries with 
the new system.

Would that be an agreeable solution ?

Regards
Bertrand


> 
>  -George