Felipe Contreras [off-list ref] writes:
And how do you know this will be part of the 1%? You don't. How many
times have you tracked regressions in transport helper's import/export
functionality? How many times in remote-hg? How many times has
*anybody* done so?
The last point makes it all the more important to have a good
history [*1*]. An area that no developer rarely touches with a little
user base can stay dormant for a long time, and when people do need
to hunt for an ancient bug or to enhance the existing feature to
support a new use case without breaking the old use case, the
original author may not be around, lost interest, or no longer uses
his own creation.
The code left behind tells us what the author thought was the best
way to solve his problem, but it does not clearly define what the
problem he tried to solve was, within what constraint he had to find
a solution for it, and why he thought that the solution was the best
(or sometimes "only") one. Log and in-code comments are to explain
such things that are beyond how the code works and what it does.
[Footnote]
*1* In this message, I am not judging if the depth of your writing
for the particular change is deep enough. It depends on how well
the reader knows the area, and there is no single right answer
to that question.
Incidentally that is why we tend to err on the more descriptive
side. The next person your commit will help may not know the
area as well as you do and has to figure things out on his
own. You are helping him by being descriptive.
On Wed, Apr 17, 2013 at 6:56 PM, Junio C Hamano [off-list ref] wrote:
Felipe Contreras [off-list ref] writes:
quoted
And how do you know this will be part of the 1%? You don't. How many
times have you tracked regressions in transport helper's import/export
functionality? How many times in remote-hg? How many times has
*anybody* done so?
The last point makes it all the more important to have a good
history [*1*]. An area that no developer rarely touches with a little
user base can stay dormant for a long time, and when people do need
to hunt for an ancient bug or to enhance the existing feature to
support a new use case without breaking the old use case, the
original author may not be around, lost interest, or no longer uses
his own creation.
You are going in circles, I said such situation was *HYPOTHETICAL*,
Phil Hord said it wasn't, and now you are bringing back more
hypothetical examples, which I would gladly address, as soon as you
accept they are HYPOTHETICAL.
Now, how about you answer the questions about the *REAL* situations
Phil Hord mentioned?
* How many times have you tracked regressions in transport helper's
import/export functionality?
Hint: zero.
* How many times in remote-hg?
Hint: zero.
* How many times has *anybody* done so?
Hint: other than me, quite possibly zero.
And then, before we consider this *hypothetical* situation, it might
be worth noticing what commit this hypothetical person would hit if
you do *not* apply this patch, and what the commit message says:
---
remote-helpers: add support for an export command
Signed-off-by: Junio C Hamano <redacted>
---
Yeah, well, glad you didn't apply my patch, wouldn't want to mess up
the code that was clearly explained by that commit message.
And before you rationalize the above commit, because maybe the
functionality was described in the documentation, it wasn't:
transport-helper.c | 132
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 120 insertions(+), 12 deletions(-)
If you do apply my patch, it turns out even the shortest version of my
commit message already gives more information to this *hypothetical*
developer person.
[Footnote]
*1* In this message, I am not judging if the depth of your writing
for the particular change is deep enough. It depends on how well
the reader knows the area, and there is no single right answer
to that question.
Incidentally that is why we tend to err on the more descriptive
side. The next person your commit will help may not know the
area as well as you do and has to figure things out on his
own. You are helping him by being descriptive.
I partially agree with this, but I think documenting the nuts and
bolts of transport-helper would be better in done in code,
documentation, tests, and mailing list analysis. And in all those
respects, I believe I've done a more than adequate job.
Cheers.
--
Felipe Contreras