.. _flycheck-style-guide:

=============
 Style Guide
=============

This document describes our code style.  It tells you what to look for when
making changes to Flycheck, or when reviewing pull requests.

Features
========

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 :ref:`separate packages
<flycheck-extensions>`.

Whether a feature is within the scope of Flycheck is the :ref:`maintainer’s
<flycheck-maintainers>` 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.

Backward compatibility
======================

Checkers and languages evolve over time, and their error format often change as
a consequence.  It is not a goal of Flycheck to work with every version of every
checker ever supported.  However, the latest Flycheck version *should always
work* with the contemporary version of a checker.

As a rule of thumb, if maintaining backward compatibility is trivial (i.e., does
not incur code maintenance costs), then we should do it.  For example, a
slightly more complex parsing regexp is OK, but doing version detection to add a
flag would most likely be too much.

Keep in mind that users may not have the choice of updating to the latest
version of a checker (e.g., ``gcc`` on Debian-based distributions).  On the
other hand, npm or Python packages are usually trivial to update.  Making an
extra effort to maintain backward compatibility for these hard-to-update
checkers is reasonable.

The integration tests that are run on our CI should always reflect the latest
supported version.

Style
=====

.. important::

   ``make check compile`` must pass on Emacs 28.1 or newer.  This command checks
   for some formatting issues and compilation errors.

   Run ``make format`` with Emacs 28.1 to automatically reformat the Emacs Lisp
   source files.

* Generally try to fit into the style of the code you see.

* Indent with the default indentation rules.

* Follow the :infonode:`(elisp)Programming Tips` for Emacs Lisp.

* Whitespace:

  * 80 characters per line.
  * Avoid tabs and trailing spaces.

* Naming:

  * Prefix all variables and functions with the name of the containing library,
    i.e. ``flycheck-`` for everything that is in :file:`flycheck.el`.

  * End boolean predicates with ``-p``, i.e. ``flycheck-valid-checker-p``.

* Avoid macros, and use them for syntax only.

* Adhere to the :infonode:`(elisp)Key Binding Conventions`.  Particularly do not
  define keys in Emacs’ reserved keymaps or in the :samp:`C-c {LETTER}` space
  for user bindings.

Libraries
=========

* 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-load`` and similar functions.

* Dependencies:

  * Use built-in Emacs libraries freely.
  * Introduce external dependencies with care.  Prefer built-in
    libraries.
  * Avoid dependencies on language-specific libraries.

* Avoid ``cl-lib``:

  * Prefer ``seq`` over ``cl-lib``.  Use list functions from
    ``cl-lib`` only as the very last resort.
  * Prefer ``let-alist`` and ``pcase`` over ``cl-destructuring-bind``.

Tests
=====

* Add comprehensive buttercup specs for new functions and commands to
  :file:`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 a new syntax checker, add both kinds of spec to
  :file:`test/specs/languages/`: a ``flycheck-buttercup-def-parse-test``
  reading output recorded from the tool, and a
  ``flycheck-buttercup-def-checker-test`` running the tool itself.  Only the
  second needs the tool installed, which is why the first is the one that keeps
  the checker honest on everybody else's machine.  :ref:`Testing your checker
  <flycheck-testing-a-checker>` walks through it, including how to record the
  output and what not to assert.

* Do not assert on anything the machine decides: a tool's version, which
  compiler answers to a name, or which quotes it prints around a symbol.  Those
  differ between contributors and between CI runners, and a spec that pins them
  fails for people who changed nothing.

Documentation
=============

* Add docstrings to all functions and variables.

* Follow the :infonode:`(elisp)Documentation Tips`.

* Take care to update our manual:

  * Document new interactive commands and user options in the :ref:`user guide
    <flycheck-user-guide>`.
  * Document new syntax checkers and new options for existing syntax checkers in
    the :ref:`list of languages <flycheck-languages>`.
  * Document new or changed version requirements for syntax checkers in the
    :ref:`list of languages <flycheck-languages>`.
  * Document changes to our build system and tooling in the :ref:`contributor’s
    guide <flycheck-contributors-guide>` or the :ref:`maintainer’s guide
    <flycheck-maintainers-guide>`.

Commits
=======

* 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
  (e.g. ``Fixes GH-42``).

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 intent 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.

`Git Commit`_ and Magit_ provide Emacs mode for Git commit messages, which helps
you to comply with these guidelines.

.. seealso::

   `A Note About Git Commit Messages`_
      Further information about good commit messages, including some motivation
      for our rules for commit messages.

.. _Git Commit: https://github.com/magit/magit/
.. _Magit: https://github.com/magit/magit/
.. _A Note About Git Commit Messages: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
