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

[Jan Beulich <jbeulich@xxxxxxxx>]

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

Jan