On Mon, Mar 24, 2025 at 10:16 AM Junio C Hamano <gitster@xxxxxxxxx> wrote:
>
> JAYATHEERTH K <jayatheerthkulkarni2005@xxxxxxxxx> writes:
>
> >> > +#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",
>
>
>
In the latest patch version I've removed the comments, since we
already added a line above saying the user has to include
`repository.h` I don't think we need to go in depth into that, do let
me know if that is not the case, looking forward to any more feedback.
