about summary refs log tree commit diff
path: root/elisp-conventions.md
diff options
context:
space:
mode:
authorWilliam Carroll <wpcarro@gmail.com>2019-10-09T11·13+0100
committerWilliam Carroll <wpcarro@gmail.com>2019-12-24T15·21+0000
commit6b456c1b7a4f6899f063a6e65355af51901d9c7a (patch)
treecfc70d74818ae9fabdbbfb0cf16cce092e4c1a09 /elisp-conventions.md
parenta7c72adb2ebec1e497fc040eaf3551d564d61a5b (diff)
Massive configuration overhaul
Currently paying the price of months of non-diligent git usage.

Here's what has changed.

- Theming support in Gvcci and wpgtk
- Dropping support for i3
- Supporting EXWM
- Many Elisp modules
- Collapsed redundant directories in ./configs
Diffstat (limited to 'elisp-conventions.md')
-rw-r--r--elisp-conventions.md20
1 files changed, 20 insertions, 0 deletions
diff --git a/elisp-conventions.md b/elisp-conventions.md
new file mode 100644
index 000000000000..0e39c3069d8b
--- /dev/null
+++ b/elisp-conventions.md
@@ -0,0 +1,20 @@
+# Elisp Conventions
+
+Some of this aligns with existing style guides. Some of it does not.
+
+In general, prefer functions with fixed arities instead of variadic
+alternatives.
+
+- Namespace functions with `namespace/function-name`
+- Use `ensure`, `assert`, `refute` whenever possible.
+- When talking about encoding and decoding, let's use the words "encoding" and
+  "decoding" rather than the myriad of other variants that appear like:
+  - `marshalling` and `unmarshalling`
+  - `parse` and `deparse`, `serialize`, `stringify`
+  - `unpickle` and `pickle` (Python)
+  - `from-string` and `to-string`
+  - TODO: Add more examples of these; there should be close to a dozen.
+- Annotate assertions with `!` endings.
+- Prefer the Scheme style of `predicate?`
+- Variadic functions *should* encode this by appending * onto their
+  name. E.g. `maybe/nil?*`