Naming conventions

Naming conventions

[Simen Endsjø]

Hi, I'm quite new to scheme/lisp and haven't coded in a dynamic 
language in many
years. I notice there are some naming conventions, but I'm not 
sure how they are
used/supposed to be used.

- *symbol* :: ? Global scope variable?
- SYMBOL :: ? Also global scope variable?
- %symbol :: ? private function?
- %symbol% :: ? private variable?
- symbol* :: ? extended version of function with same name?
- symbol? :: predicate function returning bool
- symbol! :: Non-pure/mutating function?- <<symbol>> :: ?
- <symbol> :: ? As a macro parameter, and symbol will be defined 
  in parent scope..?
- <<symbol>> :: ?
- type1->type2 :: convertion from type1 to type2

What does all of these mean? Are some of them 
anti-patterns/deprecated? Are there others?

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

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

Re: Naming conventions

[Simen Endsjø]

Thanks for your thorough answer, and I'll certainly read the 
style-guide too.
IIRC, only symbol!, symbol? and type1->type2 is really agreed 
upon, and other
conventions might vary from project to project.

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

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

Re: Naming conventions

[Zelphir Kaltstahl]

Hi Simen!

(comments in between)

On 07.07.20 13:05, Simen Endsjø wrote:
>
> Hi, I'm quite new to scheme/lisp and haven't coded in a dynamic
> language in many
> years. I notice there are some naming conventions, but I'm not sure
> how they are
> used/supposed to be used.
>
> - *symbol* :: ? Global scope variable?
> - SYMBOL :: ? Also global scope variable?
> - %symbol :: ? private function?
> - %symbol% :: ? private variable?


I have seen the % being used for objects. For example in the Racket docs
for its GUI library:
https://docs.racket-lang.org/gui/windowing-overview.html#%28part._.Creating_.Windows%29

I am not sure, whether this is a Racket-only thing.


> - symbol* :: ? extended version of function with same name?
> - symbol? :: predicate function returning bool
> - symbol! :: Non-pure/mutating function?- <<symbol>> :: ?
> - <symbol> :: ? As a macro parameter, and symbol will be defined  in
> parent scope..?
> - <<symbol>> :: ?
> - type1->type2 :: convertion from type1 to type2
>
> What does all of these mean? Are some of them
> anti-patterns/deprecated? Are there others?
>
> I also see functions named type-operation and operation-type. Is one
> preferable to the other?


Regards,

Zelphir

-- 
repositories: https://notabug.org/ZelphirKaltstahl

Re: Naming conventions

[Bonface M. K.]

Hi Zelphir \o \o

Zelphir Kaltstahl <zelphirkaltstahl@posteo.de> writes:

> Hi Simen!
>
> (comments in between)
>
> On 07.07.20 13:05, Simen Endsjø wrote:
>>
>> Hi, I'm quite new to scheme/lisp and haven't coded in a dynamic
>> language in many
>> years. I notice there are some naming conventions, but I'm not sure
>> how they are
>> used/supposed to be used.
>>
>> - *symbol* :: ? Global scope variable?
>> - SYMBOL :: ? Also global scope variable?
>> - %symbol :: ? private function?
>> - %symbol% :: ? private variable?
>
>
> I have seen the % being used for objects. For example in the Racket docs
> for its GUI library:
> https://docs.racket-lang.org/gui/windowing-overview.html#%28part._.Creating_.Windows%29
>
> I am not sure, whether this is a Racket-only thing.
>
>

It's not only confined in Racket. I've also seen in Guile(which is a
scheme too), moreso in the GUIX project

>> - symbol* :: ? extended version of function with same name?
>> - symbol? :: predicate function returning bool
>> - symbol! :: Non-pure/mutating function?- <<symbol>> :: ?
>> - <symbol> :: ? As a macro parameter, and symbol will be defined  in
>> parent scope..?
>> - <<symbol>> :: ?
>> - type1->type2 :: convertion from type1 to type2
>>
>> What does all of these mean? Are some of them
>> anti-patterns/deprecated? Are there others?
>>
>> I also see functions named type-operation and operation-type. Is one
>> preferable to the other?
>

There was an email that explained this. IMHO this depends on the project
you are working and what part of the code base you are touching. Like
you could do a `vector-length` with makes sense. But also `make-vector`
when you have a struct-like data structure makes sense too. The former
being type-operation and the latter being operation-type. Now this is
up to your good sense IMHO.

>
> Regards,
>
> Zelphir

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

Re: Naming conventions

[Taylan Kammer]

On 07.07.2020 13:05, Simen Endsjø wrote:
>
> - <symbol> :: ? As a macro parameter
>
I personally do this with pattern variables in macros, but I don't know
if anyone else does.  I'd advocate for it to become the norm though!

I find it very intuitive because pattern variables are placeholders for
something else, and the <blah> notation is often used for placeholders.
(This probably originates from BNF syntax.)

Consider the following example.

In Scheme it's customary to return #f (the false Boolean) to mean "null"
or "no result."  And it's a common pattern in code to try to get a value
from somewhere, then only do a certain thing if you got a result.

For that reason let's say I want to define an "in-case" macro, to be
used like this:

  (in-case warnings (check-warnings input)
    (display "Input is valid, but please note these warnings:\n")
    (for-each (lambda (w) (display w) (newline)) warnings))

I.e., the result of (check-warnings input) is bound to the 'warnings'
variable, and the code is executed if it's not #f.

I would define that macro like this:

  (define-syntax in-case
    (syntax-rules ()
      ((_ <variable> <expression> <body> <body*> ...)
       (let ((<variable> <expression>))
         (when <variable>
           <body> <body*> ...)))))

I personally find that significantly easier to read than this:

  (define-syntax in-case
    (syntax-rules ()
      ((_ variable expression body body* ...)
       (let ((variable expression))
         (when variable
           body body* ...)))))

In the latter variant, it's much less obvious that we have a piece of
"template" code with symbols or expressions to be inserted in certain
positions.

Especially the part with (let ((variable expression)) ...) is IMO much
clearer when using the <symbol> notation, because it makes it clear that
we're not binding a new variable literally called "variable" but rather
that, when the macro is expanded, it will bind a variable whose actual
name is provided by the user of the macro.

Maybe the difference isn't much in such a small example, but if the body
of the macro was bigger, it might help quite a bit.


I think the notation also has the benefit of making it more obvious for
newbies what exactly syntax-rules does and how it works.  In particular,
it might help to clarify that the second part of 'syntax-rules' is a
template, where snippets given by the macro user are inserted into
certain slots in the template.


- Taylan