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 justifyingthe deviation (preempting review comments).
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 |
