Skip to content

Latest commit

 

History

History
526 lines (398 loc) · 11.8 KB

README.md

File metadata and controls

526 lines (398 loc) · 11.8 KB

Linters

Below is a list of linters supported by haml-lint, ordered alphabetically.

AltText

img tags should have an accompanying alt attribute containing alternate text.

Bad

%img{ src: 'my-photo.jpg' }

Good

%img{ alt: 'Photo of me', src: 'my-photo.jpg' }

Include alt attributes is important for making your site more accessible. See the W3C guidelines for details.

ClassAttributeWithStaticValue

Prefer static class attributes over hash attributes with static values.

Bad

%tag{ class: 'my-class' }

Good

%tag.my-class

Unless you are assigning a dynamic value to the class attribute, it is terser to use the inline tag syntax to specify the class(es) an element should be assigned.

ClassesBeforeIds

List classes before IDs in tags.

Bad: ID before class

%tag#id.class

Good

%tag.class#id

These attributes should be listed in order of their specificity. Since the tag name (if specified) always comes first and has the lowest specificity, classes and then IDs should follow.

ConsecutiveComments

Consecutive comments should be condensed into a single multiline comment.

Bad

-# A collection
-# of many
-# consecutive comments

Good

-#
  A multiline comment
  is much more clean
  and concise

ConsecutiveSilentScripts

Option Description
max_consecutive Maximum number of consecutive scripts allowed before warning (default 2)

Avoid writing multiple lines of Ruby using silent script markers (-).

Bad

- expression_one
- expression_two
- expression_three

Better

:ruby
  expression_one
  expression_two
  expression_three

In general, large blocks of Ruby code in HAML templates are a smell, and this check serves to warn you of that. However, for the cases where having the code inline can improve readability, you can signal your intention by using a :ruby filter block instead.

EmptyScript

Don't write empty scripts.

Bad: script marker with no code

-

Good

- some_expression

These serve no purpose and are usually left behind by mistake.

FinalNewline

Files should always have a final newline. This results in better diffs when adding lines to the file, since SCM systems such as git won't think that you touched the last line if you append to the end of a file.

You can customize whether or not a final newline exists with the present option.

Configuration Option Description
present Whether a final newline should be present (default true)

HtmlAttributes

Don't use the HTML-style attributes syntax to define attributes for an element.

Bad

%tag(lang=en)

Good

%tag{ lang: 'en' }

While the HTML-style attributes syntax can be terser, it introduces additional complexity to your templates as there are now two different ways to define attributes. Standardizing on when to use HTML-style versus hash-style adds greater cognitive load when writing templates. Using one style makes this easier.

ImplicitDiv

Avoid writing %div when it would otherwise be implicit.

Bad: div is unnecessary when class/ID is specified

%div.button

Good: div is required when no class/ID is specified

%div

Good

.button

HAML was designed to be concise, and not embracing this philosophy makes the tool less useful.

Indentation

Check that spaces are used for indentation instead of hard tabs.

Option Description
character Character to use for indentation. space or tab (default space)

LeadingCommentSpace

Separate comments from the leading # by a space.

Bad

-#Comment with no space

Good

-# Comment with space

The latter is more readable.

LineLength

Option Description
max Maximum number of columns a single line can have. (default 80)

Wrap lines at 80 characters. You can configure this amount via the max option on the linter, e.g. by adding the following to your .haml-lint.yml:

linters:
  LineLength:
    max: 100

Long lines are harder to read and usually indicative of complexity. You can avoid them by splitting long attribute hashes on a comma, for example:

%tag{ attr1: 1,
      attr2: 2,
      attr3: 3 }

This significantly improves readability.

MultilinePipe

Don't span multiple lines using the multiline pipe (|) syntax.

Bad

%p= 'Some' + |
    'long' + |
    'string' |

Good: use helpers to generate long dynamic strings

%p= generate_long_string

Good: split long method calls on commas

%p= some_helper_method(some_value,
                       another_value,
                       yet_another_value)

Good: split attribute definitions/hashes on commas

%p{ data: { value: value,
            name: name } }

The multiline bar was made awkward intentionally. haml-lint takes this a step further by discouraging its use entirely, as it almost always suggests an unnecessarily complicated template that should have its logic extracted into a helper.

MultilineScript

Don't span Ruby script over multiple lines using operators.

Bad

- if condition ||
-    other_condition
  Display something!

Good

- if condition || other_condition
  Display something!

While writing code this way may sometimes work, it is actually a result of a quirk in how HAML generates code from a template. While the following code will compile and run:

- if condition ||
-    other_condition
  Display something!

...this code will fail with a parse error:

- if condition ||
-    other_condition
  Display something!
- else
  Otherwise display this!

Thus it's best to stay away from writing code this way.

ObjectReferenceAttributes

Don't use the object reference syntax to set the class/id of an element.

Bad

%li[@user]
  = @user.name

Good

%li.user{ id: "user_#{@user.id}" }
  = @user.name

The object reference syntax is a bit magical, and makes it difficult to find where in your code a particular class attribute is defined. It is also tied directly to the class names of the objects you pass to it, creating an unnecessary coupling which can make refactoring your models affect your views.

RuboCop

Option Description
ignored_cops Array of RuboCop cops to ignore.

This linter integrates with RuboCop (a static code analyzer and style enforcer) to check the actual Ruby code in your templates. It will respect any RuboCop-specific configuration you have set in .rubocop.yml files, but will explicitly ignore some checks that don't make sense in the context of HAML documents (like Style/BlockAlignment).

-# example.haml
- name = 'James Brown'
- unused_variable = 42

%p Hello #{name}!

Output from haml-lint

example.haml:3 [W] Useless assignment to variable - unused_variable

You can customize which RuboCop warnings you want to ignore by modifying the ignored_cops option (see config/default.yml for the full list of ignored cops).

You can also explicitly set which RuboCop configuration to use via the HAML_LINT_RUBOCOP_CONF environment variable. This is intended to be used by external tools which run the linter on files in temporary directories separate from the directory where the HAML template originally resided (and thus where the normal .rubocop.yml would be picked up).

Displaying Cop Names

You can display the name of the cop by adding the following to your .rubocop.yml configuration:

AllCops:
  DisplayCopNames: true

RubyComments

Prefer HAML's built-in comment over ad hoc comments in Ruby code.

Bad: Space after # means comment is actually treated as Ruby code

- # A Ruby comment

Good

-# A HAML comment

While both comment types will result in nothing being output, HAML comments are a little more flexible in that you can have them span multiple lines, e.g.

-# This is a multi-line
   HAML comment

SpaceBeforeScript

Separate Ruby script indicators (-/=) from their code with a single space.

Bad: no space between = and some_expression

=some_expression

Good

= some_expression

Good

- some_value = 'Hello World'

Ensuring space after -/= enforces a consistency that all HAML tags/script indicators are separated from their inline content by a space. Since it is optional to add a space after -/= but required when writing %tag or similar, the consistency is best enforced via a linter.

SpaceInsideHashAttributes

Check the style of hash attributes against one of two possible preferred styles, space (default) or no_space:

Bad: inconsistent spacing inside hash attributes braces

%tag{ foo: bar}
%tag{foo: bar }
%tag{  foo: bar }

With default space style option: require a single space inside hash attributes braces

%tag{ foo: bar }

With no_space style option: require no space inside hash attributes braces

%tag{foo: bar}

This offers the ability to ensure consistency of Haml hash attributes style with ruby hash literal style (compare with the Style/SpaceInsideHashLiteralBraces cop in Rubocop).

TagName

Tag names should not contain uppercase letters.

Bad

%BODY

Good

%body

This is a de facto standard in writing HAML documents as well as HTML in general, as it is easier to type and matches the convention of many developer tools. If you are writing HAML to output XML documents, however, it is a strict requirement.

TrailingWhitespace

HAML documents should not contain trailing whitespace (spaces or tabs) on any lines.

UnnecessaryInterpolation

Avoid using unnecessary interpolation for inline tag content.

Bad

%tag #{expression}

Good: more concise

%tag= expression

UnnecessaryStringOutput

Avoid outputting string expressions in Ruby when static text will suffice.

Bad

%tag= "Some #{interpolated} string"

Good: more concise

%tag Some #{interpolated} string

HAML gracefully handles string interpolation in static text, so you don't need to work with Ruby strings in order to use interpolation.