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

[Jan Beulich <jbeulich@xxxxxxxx>]

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).

Jan