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

From: Linus Arver <linusa@google.com>
Date: Feb 3, 2024, 01:37 UTC
Message-ID: <owly8r421g6g.fsf@fine.c.googlers.com>
In-Reply-To: <xmqqil38ypuk.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 15 quoted lines

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Linus Arver <linusa@google.com>
>>
>> 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.