Re: [PATCH] help: ensure that common-cmds.h is only included by help.c

[David Aguilar <davvid@gmail.com>]

On Sun, Sep 14, 2014 at 12:55:41AM -0700, Perry Hutchison wrote:
> Junio C Hamano <gitster@pobox.com> wrote:
> > On Sat, Sep 13, 2014 at 7:00 PM, Perry Hutchison <perryh@pluto.rain.com> wrote:
> > > David Aguilar <davvid@gmail.com> wrote:
> > >> Add a #ifndef guard to ensure that common-cmds.h can only
> > >> be included by help.c.
> > >
> > > ... If these definitions are intended to be private to help.c,
> > > why not put them there and eliminate common-cmds.h entirely?
> >
> > Have you studied where common-cmds.h comes from?
> 
> Not when I wrote that :)
> 
> > After you have done so, would you make the same suggestion?
> 
> Yes, as a matter of using C in a conventional and non-hackish
> manner.  The normal and expected purpose of .h files is to share
> definitions among compilation units.  If certain definitions are
> -- by design -- intended to be used in only a single compilation
> unit, they should not be put in a .h file; that only encourages
> other programmers who come along later to use those definitions
> in an incorrect way.
> 
> If it's too much trouble to have the auto-generation mechanism 
> insert the definitions into help.c where they belong, at least
> name the auto-generated file something else, like commands-auto.res
> or command-list.txt.  A #include file's name does not _have_ to
> end in .h, and avoiding the .h convention in a case such as this
> would make it blatantly obvious that something unconventional is
> being done.

I would generally agree.  Nonetheless, I was able to implement
this check without touching any of these files so these should
probably stay as-is.

Thanks,
-- 
David