😱

コード整形ツールを使うときはプリセットに注意しよう

2024/06/02に公開

なんだこの意味不明な警告は?!

先日、MarkuplintStylelintというコードを整形してくれるツールを導入しました。

苦労の末にインストールし、いざ実践と意気込みましたが…出てきた警告は明らかに意味不明。

直訳すると「ルールが違います」、「サポートされていません」などなど…。
何が違うのかすらも警告文は教えてくれないので、どのように設定したらよいかすらもわからない。

この記事では、私自身の経験に基づいて、これらの状況から抜け出した際の考え方や、方法をご紹介します。

各種Linterツールのバージョンと作業環境

markuplint v4.9.0
@markuplint/html-spec v4.8.0

stylelint v16.6.1
stylelint-config-standard v36.0.0

ツールの導入に関する情報はこちらの記事をご参照ください。
https://zenn.dev/kei615ykhm/articles/introducing-markuplint

【結論】シンプルな設定ファイルが最強

まずは、結論から説明します。
それぞれの公式サイトで紹介している推奨設定と、複雑になりすぎない範囲で追加設定を指定することで、ややこしさが無くなります。

私が実際に設定しているのは以下の記述です。

.markuplint.jsonの場合

{
  "extends": [
    "markuplint:recommended"
  ],
  "rules": {
    "attr-value-quotes": {
      "severity": "error",
      "value": "double"
    }
  }
}

公式の推奨設定:extends

"extends": [
  "markuplint:recommended"
]

これは、Markplintの推奨設定を継承することを示しています。推奨設定には、一般的に良いとされるルールや設定が含まれており、これを使用することで基本的な品質チェックが行えます。

個別指定の設定:rules

"rules": {
  "attr-value-quotes": {
    "severity": "error",
    "value": "double"
  }
}

・属性名:attr-value-quotes

このルールは、HTML属性値を囲む引用符の形式を指定します。

"severity": "error"

ルール違反が発見された場合に、エラーメッセージを出力します。この設定により、違反があるとビルドが失敗するなど、重大な問題として扱うことができます。

"value": "double"

属性値は二重引用符(ダブルクォート)で囲む必要があることを指定しています。
例として、<input type="text" name="username">のように、属性値を二重引用符で囲むべきことを強制できます。

この設定の意図

この設定ファイルは、基本的なマークアップの品質を保つためのルールを定義しています。
公式の推奨設定markuplint:recommendedをベースにしており、属性値の引用符形式を二重引用符に統一するルールを追加しています。

これにより、コードの一貫性と可読性が向上し、予期しないエラーを防ぐことができます。

.stylelintrc.jsonの場合

{
  "extends": "stylelint-config-standard",
  "rules": {
    "indentation": 2,
    "color-hex-case": "lower",
    "max-empty-lines": 1
  }
}

公式の推奨設定:extends

 "extends": "stylelint-config-standard"

これは、Stylelintの推奨設定を適用しています。これには、CSSの一般的なベストプラクティスに基づいた多くのルールが含まれており、コードの一貫性と品質を確保するために役立ちます。

個別指定の設定:rules

  "rules": {
    "indentation": 2,
    "color-hex-case": "lower",
    "max-empty-lines": 1
  }

indentation: 2

CSSコードの可読性と一貫性を保つために、インデントを半角スペース2つに統一します。

color-hex-case: "lower"

16進数のカラーコードを小文字で統一します。
たとえば、#FFFFFFではなく、#ffffffを使用します。

max-empty-lines: 1

連続する空行を最大1行に制限します。これにより、不要な空白が減り、コードがコンパクトで読みやすくなります。

この設定の意図

このファイルは、標準的なベストプラクティスに基づいた公式の推奨設定を適用しつつ、コードの一貫性と可読性を高めて、他の開発者との共同作業がスムーズに進むような調整をしています。
また、個別指定した大文字と小文字を混在させないこと、ムダな空白を入れないこと、インデントを深くし過ぎない設定は、自分にとっても他人にとっても読みやすいコードになると考えて取り入れたものです。

良くない例の紹介

良い例を先に紹介しましたが、ここからは私自身が実際に設定して大失敗したケースを紹介します。
設定の詳細説明は省きますのでご了承ください。

個別指定が多すぎる

{
  "extends": "markuplint:recommended",
  "rules": {
    "indentation": {
      "value": 2
    },
    "attr-duplication": true,
    "attr-no-duplication": true,
    "doctype": {
      "value": "always"
    },
    "id-duplication": true,
    "tagname-case": {
      "value": "lower"
    },
    "attr-name-style": {
      "value": "lower"
    },
    "attr-value-quotes": {
      "value": "double"
    },
    "attr-req-value": true,
    "attr-no-unnecessary-whitespace": true,
    "attr-spacing-equal": {
      "value": "always"
    },
    "indent-style": {
      "value": "space"
    }
  }
}

ざっくり説明すると、インデントを半角スペース2つまで、属性を重複させない、基本的に小文字で書くことなどを設定したものです。

一見すると、すべて大切な設定に感じます。
でも、実際にはシステムがルールを認識しない類の警告まみれになりました。

出力された警告文は以下の通りです。

・バージョンにより、適用できないルールが含まれている
・そのルールは認識できない

公式サイトを参照してるのに?!

と、正直思いました。

公式に沿って指定しているので、やっていることは正しいはず。
でもシステムに警告されてしまうとすれば、考えられる原因はひとつ。

『拡張機能の性能が追い付いていない』

ということかもしれません。

もちろん、他人のせいにするのは良くないと思います。
でも、システム側のエラーで公式サイトの設定が弾かれてしまうのであれば、可能性として十分に考えられることでもあります。

解決策

最初に結論として、シンプルなものが最強だといったのは、システムが理解しやすい範囲の指定なら問題ないと考えたからです。
一応、extendsという部分に公式の推奨設定をそのまま引用してくる記述をしているので、いたずらに複雑化させないほうが扱いやすいと感じました。

また、自身が意識すれば解決できる内容を拡張機能に頼りすぎるのも良くないと考えました。

たとえば、

 "doctype": {
      "value": "always"
    },

DOCTYPE宣言を常に必要とする記述ですが、大抵は忘れませんよね。

逆に言えば、意識していても忘れてしまいそうな空白やインデントに関しては、拡張機能で補佐すべき内容です。

『簡単にする』と『楽をする』は違うということです。

おわりに

コード整形ツールを取り入れる理由はいろいろあると思います。

・可読性を高めたい
・コードに一貫性を持たせたい
・誤った記述を訂正したい

などなど。

その考え自体は良いことかもしれませんが、私は今回の件を通して、道具に頼りすぎるのは間違っていると感じました。

精神論のようになってしまいましたが、実際のところシンプルで最小限の記述をしたらシステムは正しく認識しているので、そういうことなのでしょう…。

この記事が役に立ったら幸いです。

Discussion