emacs

emacs Best Practices

This guide outlines the definitive best practices for Emacs Lisp development and configuration. Adhere to these rules to ensure your code is maintainable, performant, and integrates seamlessly with the Emacs ecosystem.

1. Code Organization and Structure

1.1 File Headers

Every Emacs Lisp file must start with a standard header, including lexical-binding and a clear description.

❌ BAD:

;; my-feature.el
(defun my-feature-do-something () ...)

✅ GOOD:

;;; my-feature.el --- A short description of my-feature -*- lexical-binding: t; -*-
;;
;; Copyright (C) 2025 Your Name
;; Author: Your Name <[email protected]>
;; Keywords: convenience, tools
;;
;;; Commentary:
;; This library provides functions for doing X, Y, and Z.
;;
;;; Code:

(require 'cl-lib) ; Example dependency

(provide 'my-feature)
;;; my-feature.el ends here

1.2 Naming Conventions

All global symbols (functions, variables, constants) must be prefixed with a short, hyphen-separated package name. Use a double hyphen (--) for internal, non-public symbols.

❌ BAD:

(defvar foo-list nil "A list of foos.")
(defun do-something () ...)

✅ GOOD:

(defvar myproj-foo-list nil "A list of foos for My Project.")
(defun myproj-do-something (arg) ...)
(defun myproj--internal-helper (arg) ...) ; Internal function

1.3 init.el Configuration

Your init.el must be a single file, primarily using use-package. If you prefer a literate Org file, always tangle it to init.el; never use org-babel-load-file.

❌ BAD:

;; init.el
(org-babel-load-file "~/.emacs.d/init.org")
(load-file "~/.emacs.d/my-custom-settings.el")
(setq global-setting t) ; Scattered settings

✅ GOOD:

;; init.el (or tangled from init.org)
;; -*- lexical-binding: t; -*-

;; Package manager setup (e.g., straight.el or elpaca)
(setq package-enable-at-startup nil)
(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))
(eval-when-compile (require 'use-package))
(require 'use-package-ensure) ; For :ensure t

;; Global Emacs settings (use the 'emacs' pseudo-feature)
(use-package emacs
  :init
  (setq custom-file (expand-file-name "custom.el" user-emacs-directory))
  (load custom-file 'noerror 'nomessage)
  (setq-default fill-column 80
                indent-tabs-mode nil
                tab-width 2)
  :config
  (global-display-line-numbers-mode))

;; Example package configuration
(use-package my-package
  :ensure t
  :defer t ; Defer loading until needed
  :bind (("C-c m" . my-package-command))
  :config
  (setq my-package-setting t))