That said, I'm in the process of changing the context switching code
so that most of the structure becomes unnecessary.
All that's really needed in context_t is IP, SP and possibly an
argument field if we want to be fancy about new context
initialization.
OK, fair enough. Looking forward to your future changes!
Having said that, if this particular change is more-or-less just a
preparation for future intended changes, it would be nice if this could
be mentioned in the commit message. Ideally with some slightly verbose
general reasoning.
While on the topic, let me take this opportunity to express a broader
remark that does not relate to Jiri Z.'s current work. It is actually
something that I've wanted to send to this mailing list for some time
already.
I've seen many commits to HelenOS in the past few years with very brief
commit messages and zero rationale or explanation (but sometimes even
with some questionable comedic aspiration) and I am not happy about it.
I could compile a list of those commit messages that I personally find
problematic, but I really don't want to point fingers, as this remark is
more about the trend which I would like to stop than about the
individual commit messages in the past.
Clearly, there is no point in inventing artificially complicated
explanations for truly trivial and obvious changes and I am certainly
not calling for that. But, in many cases, what seems to be trivial and
obvious at the given moment (especially to the author) might not seem
trivial and obvious in a few months or years (even to the original author).
The purpose of a commit message is to bridge this mental gap between the
current understanding in the brain of the author (including the
familiarity with the specific topic and context) and the potential
confusion and lack of context in the brains of others (especially at a
later time). This certainly requires some conscious effort by the author
to empathize with the unidentified others.
There are certain rules of thumb that might help with driving this
non-trivial effort:
* A commit message is written once, but potentially read many times.
Thus additional effort by the author when writing it is an investment
into lowering the effort of the others when reading it.
* The body of the commit message should not reiterate the "what" from
the caption, but it should explain the "why". Similarly, there is no
point in explaining what is best expressed by the code itself, but the
commit message is a great opportunity to explain precisely those aspects
of the change that are poorly expressed by the code itself.
* If the change is a fix of a bug or an improvement of some existing
code, it is always good to explain why precisely was the previous code
buggy or not ideal (again, more important that the "how" is the "why"). (*)
* If the change is not standalone, but it is a part of some overarching
development, it is always useful when its place within the bigger
picture is explained. (*)
These rules of thumb are certainly just suggestions, I am not listing
them here as some kind of authoritative dogma. But I would really like
to encourage everyone to focus their attention not only on writing
excellent code (and excellent code comments), but also on writing
excellent commit messages. Thank you!
(*) This information could be potentially replaced by references to the
relevant tickets in the bug database, to discussions in the mailing
list, etc. (but, please, not just to oral discussions with no permanent
records).
Nevertheless, as a courtesy from the author to the readers, it makes
sense to at least briefly summarize the main points directly in the
commit message to save them the round-trip to the references.
M.D.
_______________________________________________
HelenOS-devel mailing list
[email protected]
http://lists.modry.cz/listinfo/helenos-devel
