Re: [[GSOC][PATCH v3] 3/3] docs: replace git_config with repo_config

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 24, 2025, 04:46 UTC
Message-ID: <xmqq34f3qbna.fsf@gitster.g>
In-Reply-To: <CA+rGoLfALoTvQuAzQPx7rqd-Zy+wMiyEbF5Y8_-2Yi-yE-2qpA@mail.gmail.com>

JAYATHEERTH K <jayatheerthkulkarni2005@gmail.com> writes:

Show 10 quoted lines

>> > +#include "builtin.h"
>> > +#include "gettext.h"
>> > +#include "config.h"
>> > +#include "repository.h"  // Required for repo_config_get_string_tmp()
>>
>> I do not think we updated Coding Guidelines to allow // comments.
>>
> Since this was a tutorial I thought this was helpful, anyways I will
> remove the comments, because I get that this would be bad practice for
> newbies.

I meant that I think our guidelines frowns upon

	#include "foo.h" // for bar()

I didn't mean a comment is necessarily bad.  IOW,

	#include "foo.h" /* for bar() */

may be OK.

But real programs will evolve and API elements that are used from a header file will change over time, so it may not be a good idea to single out a function like that in the comment. It would be much better to explain _why_ each change is made in the text that precedes the sample code. E.g.

    Add `#include "config.h"` because you want to use X and Y,
    and `#include "repository.h"` because you want to use Z.

    Then, add the following bits to the function body:

     ----
    #include "builtin.h"
    #include "gettext.h"
    #include "config.h"
    #include "repository.h"
    ...
    int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo)
    {
        const char *cfg_name;

        printf(Q_("Your args (there is %d):\n",