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

[George Dunlap <George.Dunlap@citrix.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3447 bytes --]



> On 30 May 2022, at 10:55, Jan Beulich <jbeulich@suse.com <mailto:jbeulich@suse.com>> 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.

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.

 -George

[-- Attachment #1.2: Type: text/html, Size: 7603 bytes --]

[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 488 bytes --]