Package: comment-style
comment_styleAboutcomment_styleis an opinionated tool that highlights issues related to comment
formatting.UsageCreate a samplecomment_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.pycan then be run with the given configuration file:$ python3 comment_style.py comment_style.yamlThe 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/CodesNote that tagged comments are those that start withTODO,NOTEorFIXME.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 positivesThe check for thetrailing_commentattempts 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.pyuses 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 thetrailing_commentrule.As an example, this project checks for#comments in shell scripts (.shfiles). However,#can naturally occur in shell scripts in the context of$#. This gives a false-positivetrailing_commentviolation, so this is
allowed in thecomment_style.yamlthat this project uses.DevelopmentBuild environmentThe build environment for the project is defined inbuild.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 bashNote 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.txtThese can also be installed in the build environment from the host:$ bash scripts/with_build_env.sh python3 -m pip install -r requirements.txtThe installed packages will persist between containers for the build environment
using named volumes.TestingThe project can be tested locally usingmake check, or can be tested using the
Docker build environment by running the following:$ bash scripts/with_build_env.sh make checkNote that the environment will need to have the project requirements installed
as detailed in the previous section.UploadThe package is built and upload using the following sequence:$ python3 setup.py sdist bdist_wheel --universal
$ python3 -m twine upload dist/*