<commit_before><ol class="breadcrumb">
  <li><a href="/">Home</a></li>
  <li><a href="/book/">Book</a></li>
  <li><a href="/book/1-0-0-overview/">Part One: Grokking Lisp</a></li>
  <li><a href="/book/1-01-00-lisp-bootcamp/">Common Lisp Bootcamp</a></li>
  <li class="active">Common Lisp Style Guide</li>
</ol>

## Exercise 1.1.3

# Common Lisp Style Guide

> "Anyone who considers protocol unimportant has never dealt with a cat."
> <footer><NAME>, <em>The Cat Who Walks Through Walls</em></footer>

Style is fundamental to programming&mdash;particularly in Lisp, where the unlimited power and flexibility of paradigm can easily go to your head.  A little carelessness can make for sloppy, illegible code; but if you make a point to consider your code as an art-form as well as a tool to get a job done, you, and anyone else who has to read your code later, will thank you for it.

But don't make the mistake of thinking these rules are prescriptive; and not everyone in the Lisp community agrees with them.  Consider them more like practical suggestions which will get you thinking about style, and then you and your team can decide together which style rules you want to follow for your coding aesthetic.

At this stage of learning Lisp, you may not fully appreciate all the style rules given here, or understand everything being discussed.  And that's okay.  Take a deep breath, and familiarize yourself with these points to the best of your ability, and then treat this chapter like a reference; it will mean more and more after each chapter of this book you work through, and will be something you can keep referring to with each Lisp project.

## Symbols and Naming

Clear and meaningful symbol-names in your Lisp programs are one of the most important aspects of code readability.

While there are no hard-fast rules for naming symbols in the Common Lisp standard, beyond a list of which characters are allowed, certain conventions have arisen in the Lisp community which you should know, and usually follow religiously.  There are times when you can, and may have to, break convention, but those are special cases which require experience and finesse.

Symbol names should be descriptive, short, typed in all lowercase, with words separated by a single hyphen:

```lisp
;; Example symbol names
(defun my-addition-function (&rest rest)
  (apply #'+ rest))

(deftype my-integer-type ()
  '(and integer
        (satisfies plusp)))

(defvar my-hash-table (make-hash-table :test 'equal))

(defvar my-alist '(("one" . 1)
                   ("two" . 2)
                   ("three" . 3)))

;; Note that symbol names created from strings should be in all-caps:
(intern "MY-NEW-INTERNED-SYMBOL")
```

Global variables, *i.e.*, variables declared as top-level forms with `defvar` or `defparameter`, are named using "earmuffs" because they are dynamic and special, such as the following built into Common Lisp:

```lisp
*package*
=> #<PACKAGE "COMMON-LISP-USER">
*print-base*
=> 10
```

Package internal symbols are sometimes named with a prepended percent-sign, and not exported with the package API.  These are similar in purpose to private functions, methods, and variables in other programming languages---only they can always be accessed by using the full symbol name:

```lisp
(defpackage #:my-new-package
  (:use :cl)
  (:export #:mad-adder))

(in-package :mad-adder)

;; Do some wonky stuff with a package-internal function
(defun %madder (x)
  (declare (integer x))<commit_msg>add return values to symbol name examples, ex. 1.1.3<commit_after><ol class="breadcrumb">
  <li><a href="/">Home</a></li>
  <li><a href="/book/">Book</a></li>
  <li><a href="/book/1-0-0-overview/">Part One: Grokking Lisp</a></li>
  <li><a href="/book/1-01-00-lisp-bootcamp/">Common Lisp Bootcamp</a></li>
  <li class="active">Common Lisp Style Guide</li>
</ol>

## Exercise 1.1.3

# Common Lisp Style Guide

> "Anyone who considers protocol unimportant has never dealt with a cat."
> <footer><NAME>, <em>The Cat Who Walks Through Walls</em></footer>

Style is fundamental to programming&mdash;particularly in Lisp, where the unlimited power and flexibility of paradigm can easily go to your head.  A little carelessness can make for sloppy, illegible code; but if you make a point to consider your code as an art-form as well as a tool to get a job done, you, and anyone else who has to read your code later, will thank you for it.

But don't make the mistake of thinking these rules are prescriptive; and not everyone in the Lisp community agrees with them.  Consider them more like practical suggestions which will get you thinking about style, and then you and your team can decide together which style rules you want to follow for your coding aesthetic.

At this stage of learning Lisp, you may not fully appreciate all the style rules given here, or understand everything being discussed.  And that's okay.  Take a deep breath, and familiarize yourself with these points to the best of your ability, and then treat this chapter like a reference; it will mean more and more after each chapter of this book you work through, and will be something you can keep referring to with each Lisp project.

## Symbols and Naming

Clear and meaningful symbol-names in your Lisp programs are one of the most important aspects of code readability.

While there are no hard-fast rules for naming symbols in the Common Lisp standard, beyond a list of which characters are allowed, certain conventions have arisen in the Lisp community which you should know, and usually follow religiously.  There are times when you can, and may have to, break convention, but those are special cases which require experience and finesse.

Symbol names should be descriptive, short, typed in all lowercase, with words separated by a single hyphen:

```lisp
(defun my-addition-function (&rest rest)
  (apply #'+ rest))
=> MY-ADDITION-FUNCTION

(deftype my-integer-type ()
  '(and integer
        (satisfies plusp)))
=> MY-INTEGER-TYPE

(defvar my-hash-table (make-hash-table :test 'equal))
=> MY-HASH-TABLE

(defvar my-alist '(("one" . 1)
                   ("two" . 2)
                   ("three" . 3)))
=> MY-ALIST

;; Note that symbol names created from strings should be in all-caps:
(intern "MY-NEW-INTERNED-SYMBOL")
=> MY-NEW-INTERNED-SYMBOL
   NIL
;; or you'll have to reference it in surrounding hbars as a literal, case-sensitive symbol:
(intern "my-funky-interned-symbol")
=> |my-funky-interned-symbol|
   NIL
```

Global variables, *i.e.*, variables declared as top-level forms with `defvar` or `defparameter`, are named using "earmuffs" because they are dynamic and special, such as the following built into Common Lisp:

```lisp
*package*
=> #<PACKAGE "COMMON-LISP-USER">
*print-base*
=> 10
```

Package internal symbols are sometimes named with a prepended percent-sign, and not exported with the package API.  These are similar in purpose to private functions, methods, and variables in other programming languages---only they can always be accessed by using the full symbol name:

```lisp
(defpackage #:my-new-package
  (:use :cl)
  (:export #:mad-adder))

(in-package :mad-adder)

;; Do some wonky stuff with a package-internal function
(defun %madder (x)
  (declare (integer x))
{'fraction_non_alphanumeric': 0.09104704097116843, 'fraction_numerical': 0.004828252172713478, 'mean_word_length': 4.1491477272727275, 'pattern_counts': {'":': 0, '<': 55, '<?xml version=': 0, '>': 69, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4709515', 'n_tokens_mistral': 2071, 'n_tokens_neox': 1973, 'n_words': 1002}