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

[Julien Grall <julien@xen.org>]

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