[#linting]
== Linting

{since-0-2} It might be useful to ensure that your source code follows
certain standards.  There are many programs called linters that can
help you with this.  Several of them are also supported by Eldev and
can be executed using the tool.

In its simplest form `lint` command will execute all supported linters
and let them loose on your source code in `main` target set:

    $ eldev lint

You don’t need to install anything additionally: Eldev will download
and use required packages itself.  Because of this, first linting in a
project might take a while to prepare, but later the downloaded
linters will be reused.

Currently, Eldev knows and uses the following linters:

* Emacs built-in `checkdoc`.  Verifies documentation strings of your
  functions, variables and so on for various style errors.
* {uri-package-lint}[`package-lint`], which detects erroneous package
  metadata, missing dependencies and much more.
* {uri-relint}[`relint`] that can detects errors in regular expression
  strings in your source code.
* {since-0-6} {uri-elisp-lint}[`elisp-lint`] that checks Elisp code
  for various errors — it is even more versatile than `package-lint`
  and actually optionally includes it.

In future, more linters can gain special treatmeant from Eldev (you
can also leave a feature request in the issue tracker).  The full list
can always be found using command `eldev lint --list`.

Running all the linters at once is not always what you want.  In such
a case you can just specify name (or several) of the linter you want
on the command line:

    $ eldev lint doc

Names can be simplified by dropping words “check” and “lint” from
them.  It is also possible to explicitly direct linters at certain
files, rather than verifying all at once:

    $ eldev lint re -f foo.el

Like with <<testing-simplifications,testing>>, you can omit `-f`
(`--file`) option above as long as variable `eldev-dwim` is non-nil.

Some projects, however, may decide to follow advices of certain
linters, but not the others.  You can explicitly tell Eldev about
project’s policy by adjusting one or more of variables
`eldev-lint-default`, `eldev-lint-default-excluded` and
`eldev-lint-disabled` in file `Eldev`.  All of these variables affect
which linters exactly Eldev starts when their names are not specified
explicitly.

Command `lint` sets Eldev’s exit status to non-zero if there is at
least one warning from any requested linter.  This simplifies using
linting in <<continuous-integration,continuous integration>> should
you want to do that.

[#doctor]
=== The doctor

{since-1-3} Eldev comes with a way to “lint” the project and its
checkout too.  Just run:

    $ eldev doctor

This will check the project for a few common potential problems.  All
the warnings come with quite verbose explanations, detailing what the
doctor thinks is wrong, why and how to fix that.  However, it’s up to
you to decide what and if anything at all should be done — the doctor
doesn’t, and actually cannot, fix anything itself.

Here is the current list of available checks, to give an idea of what
it verifies:

`eldev-presence`:: Checks if file `Eldev` is present.  It is possible
to run Eldev on projects that don’t have it, but some external tools
will then not recognize the project as using Eldev.
`eldev-byte-compilable`:: Earlier examples would add `no-byte-compile`
to file `Eldev`, which is now not recommended.  E.g. it would prevent
{uri-flycheck-eldev}[flycheck-eldev] and
{uri-flymake-eldev}[flymake-eldev] from checking the file.
`explicit-main-file`:: Some projects have package headers in multiple
files, which could confuse Emacs packaging system.  If you have such
headers only in one file, this test won’t complain.
`explicit-emacs-version`:: A project should always explicitly state
which Emacs version they need.  Otherwise users could install it only
to find it not working correctly in unpredictable way.
`stable/unstable-archives`:: It is generally recommended to use
<<dependencies,package archives>> `gnu-elpa`, `nongnu-elpa` or `melpa`
instead of hardcoding stable or unstable variant.  In this case you
can switch easily using command line options.
`recent-stable-releases`:: Checks if there is a recent enough
<<release,stable release>> of the project.  Otherwise users who prefer
stable releases will never see that your project has new features.
However, this test will never complain if you don’t have any stable
releases at all (i.e. if you follow “rolling release” model).
`githooks`:: Checks if project-recommended <<githooks,Git hooks>> are
activated in the working tree.  Won’t complain if there are no Git
hooks in the project.
`up-to-date-copyright`:: {since-1-6} Checks if the copyright notices
in the project’s files appear <<update-copyright,up-to-date>> with the
changes (it is a common mistake to forget updating those — I’ve seen
that not only I’m prone to that).
`eldev-file-owners`:: {since-1-4-1} Targeted at some internal bug
related to use of old Eldev versions and/or Docker.  Hopefully you’ll
never see this complain.
