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

[Miles Bader]

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!).

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,
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.

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.

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

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.