Re: Naming conventions

[Bonface M. K.]

John Cowan <cowan@ccil.org> writes:

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

I see the guix code-base make heavy(?) use of this. Here's a snippet
from `guix/build-aux/build-self.scm`:

--8<---------------cut here---------------start------------->8---
(define %config-variables
  ;; (guix config) variables corresponding to Guix configuration.
  (letrec-syntax ((variables (syntax-rules ()
                               ((_)
                                '())
                               ((_ variable rest ...)
                                (cons `(variable . ,variable)
                                      (variables rest ...))))))
    (variables %localstatedir %storedir %sysconfdir %system)))
--8<---------------cut here---------------end--------------->8---


> 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

-- 
Bonface M. K. (https://www.bonfacemunyoki.com)
One Divine Emacs To Rule Them All
GPG key = D4F09EB110177E03C28E2FE1F5BBAE1E0392253F