/style

Code style management and enforcement

Primary LanguagePython

Style

You got that James Dean daydream look in your eye

And I got that red lip, classic thing that you like

And when we go crashing down, we come back every time

'Cause we never go out of style, we never go out of style...

Taylor

Status

Branch Status
master CircleCI
staging CircleCI

Purpose of this repository

style is a small repository designed to encourage style and code checking.

"But why?", you ask.

The short answer is code maintainability (although maintainability is not the only reason why you should lint your code).

You'll find many articles on the web discussing the advantages of code linting. For example:

Reading code written in an unfamiliar style is like reading poor handwriting. The information is all there, but it requires inordinate concentration simply to extract to it. Conversely, reading code that adheres to a familiar style allows you to focus on what is important. Whether it’s someone else’s code or your own that you are returning to, having a common style greatly reduces maintainability costs.

(source: https://blog.adeptmarketing.com/how-linting-produces-better-code).

style allows you to easily install a pre-commit git hook in your local git repositories.

The hook works as follows:

  1. You commit your code.
  2. A series of linters are run on your code.
  3. If the linters find that there is something wrong with your code, your commit is rejected. In this case, simply make the appropriate edits and commit again.

Demo

Languages

Currently, style can perform code checking on files written in

Installing the pre-commit hook

  1. Please make sure that Python 3 and R are both installed on your system.

    In this example, python and pip point to the Homebrew Python 3 distribution. If you are using a different distribution, or working in a virtual environment, please make the appropriate changes in what follows.

  2. Make sure that the following are installed on your system:

    • markdownlint-cli:

      npm install -g markdownlint-cli

      npm comes with node, which you can install with brew install node on Mac.

      On Linux, you can install npm with sudo apt-get install npm.

    • the Python flake8 module:

      pip install flake8

    • the R lintr package:

      R -e "install.packages('lintr', repos = 'https://cloud.r-project.org')"

  3. Clone this repository on your system (say in ~/Git/style) and cd into it.

  4. Run the installer on the target repository (e.g. ~/Git/my-linty-repo in the following example):

    python install.py ~/Git/my-linty-repo

    If you want, you can perform the installation on more than one target repository at the same time:

    python install.py ~/Git/my-linty-repo ~/Git/my-linty-repo2 ...

    By default, the installation activates all available linters. However, you can select which linters you want to activate by means of short flags.

    For instance, in order to activate only the Python linter in ~/Git/my-linty-repo you can run

    python install.py -p ~/Git/my-linty-repo

    or, to activate the Markdown and the Python linter, but not the R linter, you can run

    python install.py -m -p ~/Git/my-linty-repo

    or

    python install.py -mp ~/Git/my-linty-repo

    Run

    python install.py -h

    to display all installation options.

Uninstalling the pre-commit hook

  1. cd into the root of the repository from which you want to remove the hook, e.g.

    cd ~/Git/my-linty-repo

  2. Run the uninstall.py script in .git/hooks/pre_commit with

    python .git/hooks/pre_commit/uninstall.py

Adding support for more linters

You can leverage the Linter class in pre_commit.linters to add support for a variety of additional linters.

Contributing to this repository

Please refer to the CONTRIBUTING.md file for instructions on how to contribute to this repository.

How to avoid code checking

Generally, you want all of your code to be checked without exceptions. However, there may be special circumstances under which you may desire to exclude a line or a block of code from being checked.

This section illustrates some ways of selectively excluding portions of your code from being checked. Please refer to the documentation of the relevant packages for more details.

Use wisely!

Mr. Burns

Markdown - markdownlint

Code in a block like this one

<!-- markdownlint-disable -->
...CODE...
<!-- markdownlint-enable -->

is not checked.

You can exclude specific errors (MD001 and MD002 in the example that follows) with:

<!-- markdownlint-disable MD001 MD002 -->
...CODE...
<!-- markdownlint-enable MD001 MD002 -->

More configuration options can be specified by including .markdownlint.json file in the root of your local repository.

Python - flake8

You can exclude an entire file from being checked by including the following line at the top of it:

# flake8: noqa

Use the # noqa inline comment to exclude a single line:

# this line will raise an error
a= 1

# this line will not raise an error,
# because it is excluded from code checking
b =2 # noqa

You can exclude specific errors on a line with # noqa: <error>, e.g. # noqa: E234.

More configuration options can be specified by including a .flake8 file in the root of your local repository.

R - lintr

Use the # nolint inline comment to exclude a given line:

# this line will raise an error
a= 1

# this line will not raise an error,
# because it is excluded from code checking
b =2 # nolint

You can exclude an entire block of code like so:

# the following block will not raise errors
# because it is excluded from code checking

# nolint start
a= 1
b =2
# nolint end

# this line will raise an error
x <- c(1,2, 3)

More configuration options can be specified by including a .lintr file in the root of your local repository.

Useful links

xkcd