Re: What's cooking in git.git (Apr 2013, #05; Mon, 15)

Felipe Contreras <felipe.contreras@gmail.com> writes:

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.