git commit messages and code comments

[sebb <se...@gmail.com>]

IMO, Git commit messages serve two purposes:
- inform the reviewer why the commit was made:
 to guard against spurious commits, they should mention all changes made
- make it easier to find the commit when scanning a file's history

Most messages should be a single line.
Sometimes there is a need for a bit more context to explain why the
commit is being made.

Any longer, and the commit probably mixes too many changes, and should be split.

Git commit messages should not include explanations of how the code works.
Such comments belong in the code source.

It should not be necessary to delve into Git logs to understand why
the code is written as it is.

Remember that the ASF releases code as source, so any information that
is necessary for the understanding of the source must be recorded in
that source.

Sebb.

Re: git commit messages and code comments

[sebb <se...@gmail.com>]

On Sun, 6 Sep 2020 at 13:20, Daniel Gruno <hu...@apache.org> wrote:
>
> On 06/09/2020 13.56, sebb wrote:
> > IMO, Git commit messages serve two purposes:
> > - inform the reviewer why the commit was made:
> >   to guard against spurious commits, they should mention all changes made
> > - make it easier to find the commit when scanning a file's history
> >
> > Most messages should be a single line.
> > Sometimes there is a need for a bit more context to explain why the
> > commit is being made.
> >
> > Any longer, and the commit probably mixes too many changes, and should be split.
> >
> > Git commit messages should not include explanations of how the code works.
> > Such comments belong in the code source.
> >
> > It should not be necessary to delve into Git logs to understand why
> > the code is written as it is.
>
> Depends on how you define "why", I'd argue.
> If I have some commentary around why/how I came to write a specific line
> of code the way I wrote it, I'd think it's perfectly fine to put that
> comment in a git commit body. There is plenty of precedence for that at
> ASF.

Yes, but that does not make it right.
There is no guarantee that future maintainers of the code will have
access to the Git logs.

> The alternative would be to it into a new email thread whenever
> something is worth noting, and that could get very spammy.

[If it is spam, then it does not belong in the Git comment either]

I would argue it belongs in the source code, or possibly in a design
document released with the source code.

> I think it's good practice to put into the code how it works in relation
> with other bits, and maybe explain in certain cases why it works the way
> it works, so that users can follow what the code does. But I don't think
> it's worth putting in the "how I came to this conclusion about how to
> write this line of code" segment into every bit of code.

If a comment is needed to understand why the code is written the way
it is, then that comment belongs in the source bundle somewhere.

Otherwise we are effectively withholding information which is needed
for future maintainers.

> >
> > Remember that the ASF releases code as source, so any information that
> > is necessary for the understanding of the source must be recorded in
> > that source.
> >
> > Sebb.
> >
>

Re: git commit messages and code comments

[Daniel Gruno <hu...@apache.org>]

On 06/09/2020 13.56, sebb wrote:
> IMO, Git commit messages serve two purposes:
> - inform the reviewer why the commit was made:
>   to guard against spurious commits, they should mention all changes made
> - make it easier to find the commit when scanning a file's history
> 
> Most messages should be a single line.
> Sometimes there is a need for a bit more context to explain why the
> commit is being made.
> 
> Any longer, and the commit probably mixes too many changes, and should be split.
> 
> Git commit messages should not include explanations of how the code works.
> Such comments belong in the code source.
> 
> It should not be necessary to delve into Git logs to understand why
> the code is written as it is.

Depends on how you define "why", I'd argue.
If I have some commentary around why/how I came to write a specific line 
of code the way I wrote it, I'd think it's perfectly fine to put that 
comment in a git commit body. There is plenty of precedence for that at 
ASF.

The alternative would be to it into a new email thread whenever 
something is worth noting, and that could get very spammy.

I think it's good practice to put into the code how it works in relation 
with other bits, and maybe explain in certain cases why it works the way 
it works, so that users can follow what the code does. But I don't think 
it's worth putting in the "how I came to this conclusion about how to 
write this line of code" segment into every bit of code.

> 
> Remember that the ASF releases code as source, so any information that
> is necessary for the understanding of the source must be recorded in
> that source.
> 
> Sebb.
>