Emacs Lisp Coding Practices
Application skill for Emacs Lisp style learning (from the archived awesome-guidelines style capsules). For major/minor mode APIs and key-binding policy details, combine with stack-specific foundations.
Core Principle
Emacs Lisp quality is namespace-safe, load-safe regularity, lexical scoping, prefixed globals, Emacs indent, and docstrings that survive checkdoc.
When to Use / NOT
- Emacs packages,
.el libraries, init snippets intended for distribution.
- Setting up
checkdoc, package-lint, byte-compile warnings in CI.
NOT when:
- One-off
M-x eval experiments not committed to a library.
- Non-Emacs Lisp code.
Workflow
- Layout, lexical-binding, indent, parens (
emacs-lisp-style-formatting-layout.md).
- Names, prefixes, private
--, predicates (emacs-lisp-style-naming-prefixes.md).
- Functions, when/unless, quotes, macros (
emacs-lisp-style-functions-macros.md).
- Packages, header, require/provide/autoload, docs (
emacs-lisp-style-packages-docs.md).
- Verify,
checkdoc-file, package-lint, byte-compile-file on changed .el files.
Red Flags
- Missing
lexical-binding: t on new files
- Hard tabs or hanging close-parens
- Unprefixed global symbols
- Side effects when library loads
- Hard-quoted lambdas in hooks/keys
(if ... (progn ...)) for multi-form branches- Autoload on internal helpers
load-library instead of require- Deprecated
cl instead of cl-lib
- Docstrings with indented continuation lines
C-c letter bindings in packages- Macros where plain functions work
Verification
emacs -batch -l checkdoc.el -f checkdoc-file -- FILE.elpackage-lint (MELPA-bound packages)byte-compile-file with warnings treated as errors (project policy)- Capsule checklist on public
defun docstrings
References
awesome-guidelines/references/emacs-lisp-style-learning-note.mdawesome-guidelines/references/emacs-lisp-style-formatting-layout.mdawesome-guidelines/references/emacs-lisp-style-naming-prefixes.mdawesome-guidelines/references/emacs-lisp-style-functions-macros.mdawesome-guidelines/references/emacs-lisp-style-packages-docs.md
1---2name: emacs-lisp-coding-practices3description: Use when authoring or reviewing Emacs Lisp, lexical-binding, lisp-case prefixes, when/unless idioms, sharp quotes, provide/require/autoload, docstrings, and checkdoc/package-lint/byte-compile in CI.4---56# Emacs Lisp Coding Practices78Application skill for Emacs Lisp style learning (from the archived `awesome-guidelines` style capsules). For major/minor mode APIs and key-binding policy details, combine with stack-specific foundations.910## Core Principle1112Emacs Lisp quality is **namespace-safe, load-safe regularity**, lexical scoping, prefixed globals, Emacs indent, and docstrings that survive `checkdoc`.1314## When to Use / NOT1516- Emacs packages, `.el` libraries, init snippets intended for distribution.17- Setting up `checkdoc`, `package-lint`, byte-compile warnings in CI.1819**NOT when:**2021- One-off `M-x eval` experiments not committed to a library.22- Non-Emacs Lisp code.2324## Workflow25261. **Layout**, lexical-binding, indent, parens (`emacs-lisp-style-formatting-layout.md`).272. **Names**, prefixes, private `--`, predicates (`emacs-lisp-style-naming-prefixes.md`).283. **Functions**, when/unless, quotes, macros (`emacs-lisp-style-functions-macros.md`).294. **Packages**, header, require/provide/autoload, docs (`emacs-lisp-style-packages-docs.md`).305. **Verify**, `checkdoc-file`, `package-lint`, `byte-compile-file` on changed `.el` files.3132## Red Flags3334- Missing `lexical-binding: t` on new files35- Hard tabs or hanging close-parens36- Unprefixed global symbols37- Side effects when library loads38- Hard-quoted lambdas in hooks/keys39- `(if ... (progn ...))` for multi-form branches40- Autoload on internal helpers41- `load-library` instead of `require`42- Deprecated `cl` instead of `cl-lib`43- Docstrings with indented continuation lines44- `C-c letter` bindings in packages45- Macros where plain functions work4647## Verification4849- `emacs -batch -l checkdoc.el -f checkdoc-file -- FILE.el`50- `package-lint` (MELPA-bound packages)51- `byte-compile-file` with warnings treated as errors (project policy)52- Capsule checklist on public `defun` docstrings535455## References5657- `awesome-guidelines/references/emacs-lisp-style-learning-note.md`58- `awesome-guidelines/references/emacs-lisp-style-formatting-layout.md`59- `awesome-guidelines/references/emacs-lisp-style-naming-prefixes.md`60- `awesome-guidelines/references/emacs-lisp-style-functions-macros.md`61- `awesome-guidelines/references/emacs-lisp-style-packages-docs.md`
ryan-brosas