Re: checkdoc (was: mh-e 6.2 imminent)

[Kim F. Storm]

Miles Bader <address@hidden> writes:

> On Mon, Oct 28, 2002 at 08:38:10PM +0100, Henrik Enberg wrote:
> > I think it's pretty natural to end them with -face.  And take something
> > like `font-lock-keyword-face', what would be a better name?
> 
> `font-lock-keyword'
> 
> [e.g., (setq font-lock-keyword-face 'font-lock-keyword) ]
> 
> > the current name is self-documenting.
> 
> If we ended every variable in `-variable', they would all be "self
> documenting" too.
> 
> The question is whether this is useful property, more than it is an annoying
> one (and I think you'll agree that calling every variable foo-variable would
> be really annoying!).

Of course we don't need that .... as long as we call the faces -face :-)

> 
> When I look at source code [I just did this using grep] that refers to
> constant face names, which is the main place where this matters, I see
> things like:
> 
>    (defface foo-face ...)
> 
>    (defvar blah-blah-face 'foo-face)
> 
>    (put-text-property X Y 'face 'foo-face)
> 
>    (set-face-foreground 'foo-face "...")
> 
>    (copy-face 'foo-face)
> 
>    (let ((face (make-face 'foo-face))) ...)
> 
>    (cons 'foo-face list-of-faces)
> 
> Note that all these cases, the `-face' in the face name doesn't help at all,

.. except if you need to grep for all uses of a given face.  I find
it more precise to grep for FOO-face rather than FOO -- which for some
FOO gives a lot of false matches.

Try to find all uses of the region and mouse faces...  I bet that you
get numerous false hits that you wouldn't have got had they been named
region-face and mouse-face.  

> because the variable/function/macro/property two which the constant face is
> being assigned/passed almost always _explicitly_ makes it clear that a face
> is being operated upon.  In the `-face' suffix seems redundant, because it's
> entirely obvious -- even to someone who doesn't understand what the source
> code does! -- that it's a face being manipulated.
> 
> I find the above situation pretty typical.

And I like all of them better than the non -face alternatives!

> 
> The main exception, as far as I can see, is font-lock specifications, which
> generally look like indecipherable gobs of hair, so the face names tend to
> stand out as the one thing who's meaning is obvious.

I fully agree re. font-lock!!

> 
> So to summarize, I don't think such face names really help at all, they just
> make the source code ugly.

Well, FWIW, I disagree.

-- 
Kim F. Storm <address@hidden> http://www.cua.dk