Re: Naming conventions

[John Cowan]

On Tue, Jul 7, 2020 at 7:06 AM Simen Endsjø <simendsjo@gmail.com> wrote:

- *symbol* :: ? Global scope variable?
>

That's a pretty standard convention, though not necessarily applied to all
global variables.  In Common Lisp (which of course is closely related to
Scheme) it is a very strong convention for variables that actually vary
(not constants).  Common Lisp also has a strong convention for writing
global constants like +foo+, but Schemers don't commonly use it.

- SYMBOL :: ? Also global scope variable?
>

Upper case and underscore generally represent an attempt to be compatible
with some C API.  The usual word-separator convention in LIsp identifiers
is the hyphen.


> - %symbol :: ? private function?
> - %symbol% :: ? private variable?
>

The %foo convention is deprecated or obsolete, as most Schemes now have
library (module) systems that make all identifiers private unless
explicitly exported.  It is present in a lot of old code from pre-library
days, though, and is generally harmless. I haven't seen any code using
%foo%.

There are no function declarations in Scheme in the sense of most
programming languages.  There are variables, some of which hold a procedure
(which itself has no name), and there is syntactic sugar for defining
variables with procedure values.  (These things are also true of
JavaScript, which was invented by a Lisper and began as "Scheme with Java's
syntax and Self's object-oriented style")


> - symbol* :: ? extended version of function with same name?
>

This is standardized in let (bind local variables in parallel) vs. let*
(bind them sequentially).  I consider it lazy because you don't know what
the * means.  Better to think of a more explanatory name even if it's
longer.


> - symbol? :: predicate function returning bool
> - symbol! :: Non-pure/mutating function
>

These two are part of the Scheme standards, and it would be Very Bad Indeed
to misuse them.  Procedures that mutate something outside Scheme may or may
not use !: for example, display and write do not. You also have to check
whether ! procedures are *guaranteed* to mutate one or more of their
arguments or merely *allowed* to do so (the latter kind are called
linear-update procedures).  Procedures guaranteed to mutate return an
unspecified value that should not be used for anything, whereas procedures
that may or may not mutate return either the mutated value or some new
value.

Somewhat confusingly, ? may be used as the name of an argument or variable
that is merely boolean rather than a procedure that returns a boolean.

?- <<symbol>> :: ?


Not sure what this means.  <foo> is sometimes used to name a record type
(names of record types don't play much of a role in Scheme), but I don't
know of any use of <<foo>>.

- <symbol> :: ? As a macro parameter, and symbol will be defined
>   in parent scope..?
>

I don't understand this either.  A minority of people prefix macro
parameters with ?.


> - type1->type2 :: convertion from type1 to type2
>

That's also heavily used in the standards, and it would again be a Very Bad
Thing to misuse it.


> I also see functions named type-operation and operation-type. Is
> one preferable to the other?
>

In general, when both type and operation are nouns, type comes first; this
groups all procedures used for a given type together, and provides an
informal namespacing convention.  Scheme is ruthlessly monomorphic, so we
have list-length, vector-length, string-length (for sets it is set-size,
because sets are unordered).  However, make- as a prefix is used to
indicate a constructor, and if the operation is a verb, putting it first
usually reads better.  A procedure named directly after a type generally
takes an arbitrary number of arguments and puts them into the new value: so
(make-list 3 'foo) => (foo foo foo), whereas (list 1 2 3) => (1 2 3).

Most of this and a great deal more can be found in Riastradh's Lisp Style
Guide at <https://mumble.net/~campbell/scheme/style.txt>.  Like all style
guides it's a bit fussy, but the first half does represent the consensus of
the Lisp community these last 60 years.

Note that Riastradh's reference to Scheme names being case-insensitive is
obsolete, although a few implementations still do it (in Common Lisp it is
still true).  The section on pagination is obsolete too: it comes down from
the days when editors typically could not fit a whole large file into
memory and you needed to work on a file page by page (often, but not
necessarily, the size of a printed page).  I would also say that
single-letter variable names are fine in local contexts: there is no great
reason to call the indices of a matrix anything but i and j.  In general,
the wider the scope of a name, the less that using abbreviation makes sense
for it.


John Cowan          http://vrici.lojban.org/~cowan        cowan@ccil.org
Arise, you prisoners of Windows / Arise, you slaves of Redmond, Wash,
The day and hour soon are coming / When all the IT folks say "Gosh!"
It isn't from a clever lawsuit / That Windowsland will finally fall,
But thousands writing open source code / Like mice who nibble through a
wall.
        --The Linux-nationale by Greg Baker