Re: Naming internal functions

[Eli Zaretskii]

> From: Christopher Schmidt <address@hidden>
> Date: Mon, 15 Apr 2013 14:46:26 +0100 (BST)
> 
> > Sounds good, tho a suggested patch would be welcome.
> 
> --- doc/lispref/tips.texi
> +++ doc/lispref/tips.texi

Thanks!

>  Lisp programs.  The names of all global variables, constants, and
>  functions in your program should begin with that chosen prefix.
>  Separate the prefix from the rest of the name with a hyphen, @samp{-}.
> -This practice helps avoid name conflicts, since all global variables
> -in Emacs Lisp share the same name space, and all functions share
> -another name address@hidden benefits of a Common Lisp-style
> +Use two hyphens if the object is not meant to be used by other
> +packages.          ^^^^^^^^^^

What "object"?  This word was never mentioned in the preceding text,
so using it here will confuse, especially those readers whose first
language is not English.  Never introduce new terminology in the
middle of a complex description, where each successive sentence builds
upon what the preceding ones said.  Always use _exactly_ the same
words as in the preceding sentences.  If you need to introduce a new
word, always describe it first.  For example:

  The names of any global objects---variables, constants, and
  functions--in your program should begin with that chosen prefix.
  Separate the prefix from the rest of the name with a hyphen, @samp{-}.
  Use two hyphens if the object is not meant to be used by other packages.

(Not that I think "objects" is good terminology in this context, but
just to show you the principle.)

> --- etc/NEWS
> +++ etc/NEWS
> @@ -409,6 +409,12 @@
>  `preserve-extended-attributes' as it now handles both SELinux context
>  and ACL entries.
>  
> +** Changes to the Emacs Lisp Coding Conventions in Emacs 24.4
> +
> +*** The package descriptor and name of global variables, constants,
> +and functions should be separated by two hypens if the object is not
> +meant to be used by other packages.

Same here.