---

D.1 Соглашения по оформлению кода на Emacs Lisp

Вот соглашения, которым вы должны следовать при написании кода на Emacs Lisp, предназначенного для широкого использования:

• Простая загрузка пакета не должна изменять поведение Emacs при редактировании. Включите команду или команды для включения и отключения функции, или для её вызова.

  Это соглашение является обязательным для любого файла, который включает определения настроек (custom). Если исправление такого файла для соответствия этому соглашению требует несовместимого изменения, смело вносите это несовместимое изменение; не откладывайте его.

• Вам следует выбрать короткое слово, чтобы отличать вашу программу от других программ на Lisp. Имена всех глобальных символов в вашей программе, то есть имена переменных, констант и функций, должны начинаться с этого выбранного префикса. Отделяйте префикс от остальной части имени дефисом, ‘-’. Эта практика помогает избежать конфликтов имён, поскольку все глобальные переменные в Emacs Lisp используют одно пространство имён, а все функции — другое³⁵. Используйте два дефиса для разделения префикса и имени, если символ не предназначен для использования другими пакетами.

  Иногда для имени команды, предназначенной для использования пользователями, удобнее, если некоторые слова стоят перед префиксом имени пакета. Например, у нас принято, чтобы команды, перечисляющие объекты, назывались ‘list-что-то’, например, пакет под названием ‘frob’ мог бы иметь команду ‘list-frobs’, тогда как другие его глобальные символы начинаются с ‘frob-’. Также конструкции, определяющие функции, переменные и т. д., могут работать лучше, если они начинаются с ‘define-’, так что допустимо помещать префикс имени позже в имени. Вне этих хорошо установленных случаев, однако, лучше предпочесть добавление вашего префикса в начало.

  Если вы пишете функцию, которая, по вашему мнению, должна быть добавлена в Emacs под определённым именем, например twiddle-files, не называйте её так в своей программе. Назовите её mylib-twiddle-files в своей программе, и отправьте письмо на адрес ‘bug-gnu-emacs@gnu.org’ с предложением добавить её в Emacs. Если и когда мы это сделаем, мы сможем легко изменить имя.

  Если одного префикса недостаточно, ваш пакет может использовать два или три альтернативных общих префикса, если они имеют смысл.

• Мы рекомендуем включать lexical-binding в новом коде и преобразовывать существующий код Emacs Lisp для включения lexical-binding, если он ещё не использует его. См. Выбор диалекта Lisp.
• Помещайте вызов provide в конце каждого отдельного Lisp-файла. См. Возможности (Features).
• Если файл требует, чтобы другие Lisp-программы были загружены заранее, то в комментариях в начале файла следует это указать. Также используйте require, чтобы убедиться, что они загружены. См. Возможности (Features).
• Если файл foo использует макрос, определённый в другом файле bar, но не использует никакие функции или переменные, определённые в bar, то foo должен содержать следующее выражение:

  (eval-when-compile (require 'bar))
  

  Это указывает Emacs загрузить bar непосредственно перед байт-компиляцией foo, чтобы определение макроса было доступно во время компиляции. Использование eval-when-compile позволяет избежать загрузки bar, когда скомпилированная версия foo используется. Этот вызов должен находиться перед первым использованием макроса в файле. См. Макросы и байт-компиляция.

• Избегайте загрузки дополнительных библиотек во время выполнения, если они действительно не нужны. Если ваш файл просто не может работать без некоторой другой библиотеки, то просто используйте require для этой библиотеки на верхнем уровне и покончите с этим. Но если ваш файл содержит несколько независимых функций, и только одна или две требуют дополнительную библиотеку, то рассмотрите возможность размещения выражений require внутри соответствующих функций, а не на верхнем уровне. Или используйте выражения autoload для загрузки дополнительной библиотеки при необходимости. Так люди, которые не используют эти аспекты вашего файла, не будут вынуждены загружать дополнительную библиотеку.
• Если вам нужны расширения Common Lisp, используйте библиотеку cl-lib вместо старой библиотеки cl. Последняя библиотека устарела и будет удалена в будущей версии Emacs.
• При определении основного режима (major mode) следуйте соглашениям по основным режимам. См. Соглашения по основным режимам.
• При определении вспомогательного режима (minor mode) следуйте соглашениям по вспомогательным режимам. См. Соглашения по написанию вспомогательных режимов.
• Если назначение функции — сообщать вам, истинно ли некоторое условие или ложно, дайте функции имя, оканчивающееся на ‘p’ (что означает “предикат”). Если имя состоит из одного слова, добавьте просто ‘p’; если имя состоит из нескольких слов, добавьте ‘-p’. Примеры: framep и frame-live-p. Мы рекомендуем избегать использования этого суффикса -p в именах булевых переменных, если только переменная не привязана к функции-предикату; вместо этого используйте суффикс -flag или имена вида is-foo.
• Если назначение переменной — хранить одну функцию, дайте ей имя, оканчивающееся на ‘-function’. Если назначение переменной — хранить список функций (т. е. переменная является хуком), пожалуйста, следуйте соглашениям по именованию хуков. См. Хуки (Hooks).
• Использование unload-feature отменяет изменения, обычно выполняемые загрузкой возможности (например, добавление функций в хуки). Однако, если загрузка feature выполняет нечто необычное и более сложное, вы можете определить функцию с именем feature-unload-function и сделать так, чтобы она отменяла любые такие специальные изменения. unload-feature затем автоматически запустит эту функцию, если она существует. См. Выгрузка.
• Определять псевдонимы для примитивов Emacs — плохая идея. Обычно вам следует использовать стандартные имена. Случай, когда псевдоним может быть полезен, — это когда он облегчает обратную совместимость или переносимость.
• Если пакет должен определить псевдоним или новую функцию для совместимости с какой-либо другой версией Emacs, называйте его с префиксом пакета, а не сырым именем, под которым он встречается в другой версии. Вот пример из Gnus, который предоставляет множество примеров таких проблем совместимости.

  (defalias 'gnus-point-at-bol
    (if (fboundp 'point-at-bol)
        'point-at-bol
      'line-beginning-position))
  

• Переопределять или советовать (advise) примитив Emacs — плохая идея. Это может сделать правильную вещь для конкретной программы, но невозможно предсказать, какие другие программы могут из-за этого сломаться.
• Также плохой идеей является советовать функцию в другом Lisp-пакете (см. Советы (Advisng) для функций Emacs Lisp).
• Избегайте использования eval-after-load и with-eval-after-load в библиотеках и пакетах (см. Хуки для загрузки). Эта возможность предназначена для пользовательских настроек; использование её в Lisp-программе нечистоплотно, поскольку оно изменяет поведение другого Lisp-файла способом, который не виден в этом файле. Это препятствует отладке, примерно как советование функции в другом пакете.
• Если файл заменяет какие-либо стандартные функции или библиотечные программы Emacs, в заметных комментариях в начале файла следует указать, какие функции заменяются и чем поведение замен отличается от поведения оригиналов.
• Конструкции, определяющие функцию или переменную, должны быть макросами, а не функциями, и их имена должны начинаться с ‘define-’. Макрос должен принимать определяемое имя в качестве первого аргумента. Это поможет различным инструментам автоматически находить определение. Избегайте конструирования имён внутри самого макроса, поскольку это может запутать эти инструменты.
• В некоторых других системах существует соглашение выбирать имена переменных, которые начинаются и заканчиваются на ‘*’. Мы не используем это соглашение в Emacs Lisp, поэтому, пожалуйста, не используйте его в своих программах. (Emacs использует такие имена только для буферов специального назначения.) Люди найдут Emacs более целостным, если все библиотеки будут использовать одни и те же соглашения.
• Система кодирования по умолчанию для исходных файлов Emacs Lisp — UTF-8 (см. Текстовые представления). В редком случае, если ваша программа содержит символы, которые не входят в UTF-8, вы должны указать соответствующую систему кодирования в строке ‘-*-’ исходного файла или в списке локальных переменных. См. Локальные переменные в файлах в Руководстве по GNU Emacs.
• Форматируйте файл, используя параметры отступов по умолчанию.
• Не берите в привычку ставить закрывающие скобки на отдельных строках; программисты на Lisp находят это сбивающим с толку.
• Пожалуйста, помещайте уведомление об авторских правах и разрешение на копирование в файл, если вы распространяете копии. См. Стандартные заголовки для библиотек Emacs.
• Для переменных, содержащих (или функций, возвращающих) имя файла или каталога, избегайте использования path в их имени, предпочитая вместо этого file, file-name или directory, поскольку Emacs следует соглашению GNU использовать термин path (путь) только для путей поиска, которые являются списками имён каталогов.