この記事はレコチョク Advent Calendar 2023 の3日目の記事となります。

はじめまして。
新卒2年目フロントエンドエンジニアの望月と申します。
音楽はK-POPアイドルが大好きです！

普段は採用サイトやPlayPASS Webサイト、レコチョクなどのサービスのフロント領域の開発を行っています。

コードが汚い問題

開発を行う上での悩みの一つに、コードが汚い問題があります。
その中でも、特に注意して見れば気づくし修正できるのに、という箇所の見落としが多くコードレビューで指摘をいただいて気づくことが多々あります。

例えば、

スペースが入っていない
むしろスペースが多い
カラーコードの指定の仕方が揃っていない( #fff と #ffffff と #FFFFFF が混じってる…)
CSSプロパティの順番が開発規約通りでない

などです。

コードの可読性やメンテナンス性、バグを防ぐためにも、開発規約に沿った統一感のあるコードを書いていきたいと思いチェックしながら進めてはいるのですが、この作業には以下のような問題があります。

どんなに注意していても目視だと見落としが発生してしまう
開発規約を全部覚えていられないため、何度も規約を照らし合わせて確認することがある
新しくプロジェクトに入る場合、開発規約を全て読む・覚える作業が負担
そして意外と時間がかかる

などです。
これらの確認作業の問題を解決し、かつコードの可読性を高めるという目的を達成するべく、今回は Stylelint を導入してみようと思います。

Stylelintとは

StylelintはCSSやSassなどスタイルシート言語の静的解析ツールで、設定したルールに沿っていない記述を検出してくれます。
これによって、ルールを設定しておけばツールが問題を拾って教えてくれるため、目視確認による見落としをなくすことができます。

前提

今回Stylelintを導入する環境として、Node.jsとnpmがインストール済みであることを前提とし、SCSSのコードの検証を行うことを目的とします。

インストール

まずはターミナルからStylelintをインストールします。

インストール手順は公式のGetting startedに従って進めます。今回は npm を使ってインストールしていきます。

インストールコマンドは以下です。

$ npm install --save-dev stylelint stylelint-config-standard-scss

stylelint-config-standard-scss

stylelint-config-standard-scss はSCSS向けの、おすすめの基本ルール設定のようなものです。

設定内容はGitHubで公開されており、以下から確認することができます。

Config設定は必須なのか

Config設定のインストールは必須ではなく、インストールしない場合は1から自分で好きなルールを設定していくことになります。

今回は試しに stylelint-config-standard-scss をインストールしてみようと思います。

設定ファイル

インストールが完了すると、設定ファイル、 .stylelintrc.json が作成されます。
作成されていない場合は、自分で作成してしまって大丈夫です。

stylelint-config-standard-scss をインストールした場合の .stylelintrc.json の中身は以下になります。

{ 
  "extends":  [
    "stylelint-config-standard-scss"
  ] 
}

先ほど少し触れた通り、Stylelintは検証したいルールを自分で設定することができます。

その場合は .stylelintrc.json にルール設定を追記していくことになるのですが、試しにいくつか設定してみるとこんな感じです。

{ 
  "extends":  [
    "stylelint-config-standard-scss"
  ] ,
  "rules": {
    "block-no-empty": true,
    "declaration-block-no-redundant-longhand-properties": true,
    "color-hex-length": "short"
  }
}

"block-no-empty": true ：スタイルの当たっていない空のブロックを許可しない

// ○
p {
    font-size: 24px;
}

// ×
p {
}

"declaration-block-no-redundant-longhand-properties": true ：プロパティを省略記法で書ける場合、冗長な書き方を許可しない。

// ○
p {
    padding: 12px 16px 24px;
}

// ×
p {
    padding-top: 12px;
    padding-right: 16px;
    padding-bottom: 24px;
    padding-left: 16px;
}

"color-hex-length": "short" ：カラーコードを省略記法で書ける場合、冗長な書き方を許可しない。

// ○
p {
    color: #fff;
}

// ×
p {
    color: #ffffff;
}

Stylelintで設定できるルールとその説明は公式サイトのRulesに一覧が掲載されているため、ここから自分で設定したいルールを探すことができます。

※Deprecated以下に掲載されているルールは、最新版のStylelint v15から非推奨になったルール達で、今後削除される可能性があるため注意が必要です。

実行してみる

実行コマンドを叩くことで、 .stylelintrc.json に設定したルールに従ってコードを検証することができます。

// npmディレクトリ配下のscssファイルを全て検証する
npx stylelint npm/**/*.scss

// `npm/sass/main.scss`を検証する
npx stylelint npm/sass/main.scss

実行すると検知したコード内のルール違反たちがずらずらと並びます。
これらを1つずつ修正していくことで、抜け漏れなくコードのミスを修正することができます。

自動修正

問題の箇所を検知できたはいいが修正がめんどくさい。
どうせなら修正までやってほしい。
という場合は、オプション --fix を付けることで、コードの検証と自動修正を一気にやってくれます。

npx stylelint npm/sass/main.scss --fix

ただ、自動修正はすべてのルールに対して行えるわけではなく、自動修正が困難な問題については手動で修正する必要があります。

先ほど設定したルール例の場合、 "color-hex-length": "short" は自動修正を行ってくれますが、 "block-no-empty": true は問題の箇所を検知するのみのため、修正は手動で行う必要があります。

加えて、コード内に例外として意図的に書き方をルール通りではないものに変えている箇所がある場合は、自動修正によって気付かぬうちに書き換えられてしまう可能性があるため、そちらも注意が必要です。

VSCodeの拡張機能について

Stylelintによるコードの検証はコマンドラインから実行コマンドを叩くだけでも行えますが、VSCodeの公式の拡張機能を使用することで、コマンドを叩かず自動で実行できるようにもなります。

まずはVSCodeの拡張機能でStylelintをインストールします。

次に .vscode/settings.json に設定を追加します。
settings.json が無い場合は作成して大丈夫です。

{
    "css.validate": false,
    "scss.validate": false,
    "stylelint.validate": ["css", "scss"],
    "stylelint.configFile": "./.stylelintrc",
    "editor.codeActionsOnSave": {
        "source.fixAll.stylelint": true
    }
}

"css.validate": false 、 "scss.validate": false"
VSCodeの組み込みのCSS,SCSSの検証を無効化し、Stylelintとの検証の競合が発生しないようにしています。
"stylelint.validate": ["css", "scss"]
指定された拡張子(ここではCSSとSCSS)のファイルに対して検証を有効にしています。
"stylelint.configFile": "./.stylelintrc"
ルールを設定した stylelintrc.json のパスを設定します。 .json は省略することができます。
"editor.codeActionsOnSave": { "source.fixAll.stylelint": true }
ファイルを保存したタイミングでStylelintの自動修正が可能な問題があれば修正を行います。

上記の設定を行うことで自動でStylelintの検証を行うことができるようになります。

最後に

コードの細かい記述ルールの確認作業の問題や負担を減らし、かつコードの可読性を高める、という目的のもとStylelintを導入をしてみました。
これからまだまだルール設定の調査が必要ですが、簡単な設定だけでも間違いを検知してくれるというのはとても助かるなあと実感しました。

ただ、設定できるルールについてもっと柔軟だったらいいのにと感じる部分もあり、すでにコーディングルールがしっかり決まっているところに導入する場合は、むしろコーディングルールに沿ったルールが用意されていない、合わないという問題が出てきそうだとも感じたため、開発状況によっては他のツールの調査と検討をするのも良さそうです。

明日のレコチョク Advent Calendar 2023 は4日目AWS CloudFormation でセキュリティグループを更新する際の罠（注意点）です。お楽しみに！

この記事はレコチョクのエンジニアブログの記事を転載したものとなります。