Subject: Re: [PATCH v3 06/10] trailer: spread usage of "trailer_block" language

From: Linus Arver <[email-masked]>
Date: Fri, 02 Feb 2024 17:37:27 -0800

Junio C Hamano <[email-masked]> writes:

> "Linus Arver via GitGitGadget" <[email-masked]> writes:
>
>> From: Linus Arver <[email-masked]>
>>
>> Deprecate the "trailer_info" struct name and replace it with
>> "trailer_block". The main reason is to help readability, because
>> "trailer_info" on the surface sounds like it's about a single trailer
>> when in reality it is a collection of contiguous lines, at least 25% of
>> which are trailers.
>
> Yup, "info" is usually a fairly meaningless word.  At least "block"
> may imply it is a collection of trailers.
>
> The naming would not matter as much to the API users, if the thing
> is now opaque, though.

You make an interesting point (and I agree).

If we were to provide additional private structs named "trailer_<foo>"
at that point we should think about how these <foo> parts "interact"
with each other (if you will) in terms of names. For example we probably
would never want to name a struct "trailer_block_parser" if it has no
relationship to the existing "trailer_block" struct. More elaborate APIs
might design a particular naming scheme (with some rules about certain
suffixes, perhaps, for opaque pointers that all behave a certain way).

But such naming considerations would naturally come into view
independent of this public vs public struct discussion, so I think the
above paragraph is moot.