This document describes our code style. It tells you what to look for when making changes to Flycheck, or when reviewing pull requests.
Flycheck’s scope and focus is providing the infrastructure and foundations for on-the-fly syntax checking. Flycheck provides the basics but deep integration with particular programming languages is best left to separate packages.
Whether a feature is within the scope of Flycheck is the maintainer’s judgement call. Generally we reserve the right to reject any pull request for being out of scope.
- Avoid a disproportionate amount of code for a single syntax checker or language. Look at the built-in checkers for judgement. A syntax checker that requires a lot more code than any built-in checker is likely to be rejected.
- Avoid deep integration with a particular UI or completion framework. Emacs’ standard is our standard: We will reject code that is tied to Helm or Counsel.
- Likewise do not deviate from Emacs’ default behaviour too much. Stick to Emacs’ standard for key bindings, interactive functions, etc.
make check compile must pass on Emacs 25 or newer. This command checks
for some formatting issues and compilation errors.
make format with Emacs 25 to automatically reformat the Emacs Lisp
- Generally try to fit into the style of the code you see.
- Indent with the default indentation rules.
- Follow the Programming Tips(elisp) for Emacs Lisp.
- 80 characters per line.
- Avoid tabs and trailing spaces.
- Prefix all variables and functions with the name of the containing library,
flycheck-for everything that is in
- End boolean predicates with
- Prefix all variables and functions with the name of the containing library, i.e.
- Avoid macros, and use them for syntax only.
- Adhere to the Key Binding Conventions(elisp). Particularly do not
define keys in Emacs’ reserved keymaps or in the
C-c LETTERspace for user bindings.
- Do not advise built-in or 3rd party functions and commands.
- Do not redefine built-in or 3rd party functions, unless for compatibility, but then copy the newer definition verbatim.
- Do not use
with-eval-after-loadand similar functions.
- Use built-in Emacs libraries freely.
- Introduce external dependencies with care. Prefer built-in
dash.elis fine, though.
- Avoid dependencies on language-specific libraries.
cl-lib. Use list functions from
cl-libonly as the very last resort.
- Add comprehensive buttercup specs for new functions and commands to
test/specs/. Check whether the specs fit into an existing spec file, or add a new file instead. In doubt, use a new file.
- For new syntax checkers add at least one syntax checker integration test to
test/flycheck-test.el. Make sure that the test passes with
make LANGUAGE=language integ.
- Add docstrings to all functions and variables.
- Follow the Documentation Tips(elisp).
- Take care to update our manual:
- Document new interactive commands and user options in the user guide.
- Document new syntax checkers and new options for existing syntax checkers in the list of languages.
- Document new or changed version requirements for syntax checkers in the list of languages.
- Document changes to our build system and tooling in the contributor’s guide or the maintainer’s guide.
- Make each commit self-contained.
- Squash trivial fixes into previous commits so that no commit in and by itself violates this style guide.
- Write commit messages that adhere to the style illustrated below.
- In doubt prefer long messages over short messages. Take the time to write a good message that explains the intention of the change and illustrates noteworthy aspects of the implementation.
- If the commit fixes a bug try to reproduce a brief description of the bug in
the message and make sure to mention the corresponding GitHub issue
Commit message style¶
This model commit message illustrates our style:
Fix a foo bug The first line is the summary, 50 characters or less. Write in the imperative and in present tense: “Fix bug”, not “fixed bug” or “fixes bug”. Explain the intend of the change not the actual contents which the diff already provides After the summary more paragraphs with detailed explanations may follow, wrapped at 72 characters. Separate multiple paragraphs by blank lines. You may use simple formatting like *emphasis* or _underline_, but keep it to a minimum. Commit messages are not in Markdown :) Commit messages may reference issues by number, like this: See GH-42. Please use `GH-` to prefix issue numbers. You may also close issues like this: Fixes GH-42 and closes GH-42.
- A Note About Git Commit Messages
- Further information about good commit messages, including some motivation for our rules for commit messages.