Re: [PATCHv2 2/2] git-patch-id: do not trip over "no newline" markers

[Jeff King <peff@peff.net>]

On Fri, Feb 18, 2011 at 09:02:23AM +0100, Michael J Gruber wrote:

> > Wow, that's pretty obscure. I wonder if the test should be factored out
> > into line_is_no_newline_at_end_of_file() (or surely there is some more
> > sensible name), and used by both apply and patch-id. Along with a nice
> > comment (which I see apply already has) describing what in the world the
> > magic number 12 means.
> 
> So, where do you suggest it should go? As far as I can see, we have two
> places reading these markers (the above builtins) and two places writing
> them (diff.c, xdiff/xutils.c), at least for git-core.

I think you could ignore the writers, as they are much more
straightforward.  But...

> (git-gui's diff.tcl has its own strict check etc.)

Ugh. Factoring that out with the C code would not be easy. :)

> I would opt for putting a more detailed explanation in the commit
> message (reasoning + ref. to apply.c) rather then trying to factor this.

I think that's OK. It's not a lot of code, it's just very non-obvious.
So a comment is probably as good as a refactor.

> After all, our code is largely undocumented as far as inline
> documentation goes (it has frustrated me a few times), and the more
> comprehensive documentation are the commit messages which git blame
> points you to.

Yeah, it is sometimes annoying. On the other hand, you know that a
comment in the commit log cannot be stale, because you are viewing it in
context (well, it can be, but theoretically you have the tools to
determine that).

I'm not sure what the right balance is. I tend to write inline comments
for small non-obvious things (e.g., why a variable is being strdup'd),
and describe the bigger picture in the commit message (e.g., why a
particular algorithm was chosen).

But it has only been a few years that we've had version control systems
where history browsing wasn't absolutely horrendous. Maybe in another
decade or so there will be best practices for this sort of thing. :)

-Peff