Understanding internal use functions

Understanding internal use functions

[Paul W. Rankin]

Hello,

I saw this in the Elisp manual:

> By convention, if a function’s symbol consists of two names separated
> by ‘--’, the function is intended for internal use and the first part
> names the file defining the function.  For example, a function named
> ‘vc-git--rev-parse’ is an internal function defined in ‘vc-git.el’.
> Internal-use functions written in C have names ending in ‘-internal’,
> e.g., ‘bury-buffer-internal’.  Emacs code contributed before 2018 may
> follow other internal-use naming conventions, which are being phased
> out.
(info "(elisp) Function Names")

How should I decide whether a function is for internal use, as opposed 
to just another function?

A command, i.e. (commandp FUNCTION) -> t, is interactive and so clearly 
not intended for internal use, but I assume this does not mean all 
non-interactive functions should be considered internal use?

It seems easier for internal use variables; if the user changes the 
`this--internal-variable' then the program may not work. Functions leave 
me a bit more bewildered... Or should I just think of it in the same 
way, e.g. "don't run this function yourself or you'll break things"?

--
https://www.paulwrankin.com

Re: Understanding internal use functions

[Tassilo Horn]

"Paul W. Rankin" <hello@paulwrankin.com> writes:

Hi Paul,

> How should I decide whether a function is for internal use, as opposed
> to just another function?
>
> A command, i.e. (commandp FUNCTION) -> t, is interactive and so clearly not
> intended for internal use, but I assume this does not mean all non-interactive
> functions should be considered internal use?

Obviously not!

> It seems easier for internal use variables; if the user changes the
> `this--internal-variable' then the program may not work. Functions
> leave me a bit more bewildered... Or should I just think of it in the
> same way, e.g. "don't run this function yourself or you'll break
> things"?

This applies to any function or variable, e.g., activate lisp-mode (a
command) in a JavaScript file, or set auto-mode-alist to "Hello world".
That just doesn't make sense and won't work but of course they are
non-internal nevertheless.

Internal functions/variables usually convey the meaning of "don't rely
on me because I might change whenever my author likes".  So it's more a
hint to programmers than to users.

For users, internal functions and variables are usually invisible
because they are never commands or customizable variables.

Bye,
Tassilo

Re: Understanding internal use functions

[Paul W. Rankin]

On Mon, May 06 2019, Tassilo Horn wrote:
>> It seems easier for internal use variables; if the user changes the
>> `this--internal-variable' then the program may not work. Functions
>> leave me a bit more bewildered... Or should I just think of it in the
>> same way, e.g. "don't run this function yourself or you'll break
>> things"?
>
> This applies to any function or variable, e.g., activate lisp-mode (a
> command) in a JavaScript file, or set auto-mode-alist to "Hello 
> world".
> That just doesn't make sense and won't work but of course they are
> non-internal nevertheless.
>
> Internal functions/variables usually convey the meaning of "don't rely
> on me because I might change whenever my author likes".  So it's more 
> a
> hint to programmers than to users.

So I should name a functions as internal as a way to imply "hey don't 
use this in other programs" (for whatever reason)?

-- 
https://www.paulwrankin.com

Re: Understanding internal use functions

[Tassilo Horn]

"Paul W. Rankin" <hello@paulwrankin.com> writes:

>> Internal functions/variables usually convey the meaning of "don't
>> rely on me because I might change whenever my author likes".  So it's
>> more a hint to programmers than to users.
>
> So I should name a functions as internal as a way to imply "hey don't
> use this in other programs" (for whatever reason)?

Yes.  And inversely, if you've written a public (non-internal) function
in your package, better assume that someone somewhere is already using
it in her config, so don't change its interface if not absolutely
necessary.

Bye,
Tassilo