comment-style 0.1.1
An opinionated comment style checker.
License: MIT
Requires Python: >=3.5.0

`comment_style`
===============

About
-----

`comment_style` is an opinionated tool that highlights issues related to comment
formatting.

Usage
-----

Create a sample `comment_style.yaml`:

      # The set of paths to test is built up in a sequence of inclusions and
      # exclusions.
    - paths:
      - include: '**/*.go'
      - exclude: 'target/**'

      comment_markers:
        line: '//'
        # The `block` field is optional. Any lines starting with a block comment
        # marker will be flagged as an error.
        block: '/*'

      allow:
        # See the "False positives" section for more details on why it may be
        # necessary to allow `trailing_comment` violations.
      - trailing_comment

    - paths:
      - include: '**/*.py'
      - exclude: 'target/**'
      comment_markers:
        line: '#'

`comment_style.py` can then be run with the given configuration file:

    $ python3 comment_style.py comment_style.yaml

The above will output any rule violations found in the discovered Go source
files. The configuration file contains a list of rules to enable checking for
different comment markers with a single configuration file.

Rules/Codes
-----------

Note that tagged comments are those that start with `TODO`, `NOTE` or `FIXME`.

* `block_comment`: Block comments aren't allowed.
* `block_starts_empty`: Comment blocks can't start with an empty line.
* `block_ends_empty`: Comment blocks can't end with an empty line.
* `no_leading_space`: Non-empty line comments must start with a space.
* `no_leading_space_after_tag`: Tagged comments  must start with a space.
* `starts_with_lowercase`: Letters at the start of comments must be capitalised.
* `starts_with_lowercase_after_tag`: Letters at the start of tagged comments
  must be capitalised.
* `no_section_ending_punctuation`: Sections of comment blocks must end with `.`
  or `:`.
* `no_ending_punctuation`: Comment blocks must end with `.`.
* `trailing_comment`: Comments must be on their own line.

### False positives

The check for the `trailing_comment` attempts to check whether the comment
marker is within a string to avoid false positives. However, to do this in a
language-independent way, `comment_style.py` uses a heuristic approach rather
than a syntactic one. Because of this, and because the heuristic only applies to
individual lines and not groups of lines, false positives (and false negatives)
can occur. This is especially so in the case of multi-line strings. Depending on
the scenario it may be necessary to allow violations of the `trailing_comment`
rule.

As an example, this project checks for `#` comments in shell scripts (`.sh`
files). However, `#` can naturally occur in shell scripts in the context of
`$#`. This gives a false-positive `trailing_comment` violation, so this is
allowed in the `comment_style.yaml` that this project uses.

Development
-----------

### Build environment

The build environment for the project is defined in `build.Dockerfile`.  The
build environment can be replicated locally by following the setup defined in
the Dockerfile, or Docker can be used to mount the local directory in the build
environment by running the following:

    $ bash scripts/with_build_env.sh bash

Note that the requirements for the project must be installed before doing
anything. These can be installed locally, or through the interactive Bash
session started above:

    $ python3 -m pip install -r requirements.txt

These can also be installed in the build environment from the host:

    $ bash scripts/with_build_env.sh python3 -m pip install -r requirements.txt

The installed packages will persist between containers for the build environment
using named volumes.

### Testing

The project can be tested locally using `make check`, or can be tested using the
Docker build environment by running the following:

    $ bash scripts/with_build_env.sh make check

Note that the environment will need to have the project requirements installed
as detailed in the previous section.

### Upload

The package is built and upload using the following sequence:

    $ python3 setup.py sdist bdist_wheel --universal
    $ python3 -m twine upload dist/*