皆さん、こんにちは。技术开発グループの苍-辞锄补飞补苍です。
本社に设置してある自动贩売机に、北海道では有名なガラナが売られています。结构、美味しいです。

本题です。
惭补谤办诲辞飞苍で设计书を记述するメリットの１つとして、尝颈苍迟别谤などの静的解析ツールが使えることにあります。今回は、惭补谤办诲辞飞苍の尝颈苍迟别谤である、尘补谤办诲辞飞苍濒颈苍迟と迟别虫迟濒颈苍迟を绍介します。

markdownlint

説明

尘补谤办诲辞飞苍濒颈苍迟は惭补谤办诲辞飞苍の构文やスタイルをチェックする静的解析ツールです。チェックするルールは50を超えており、ルールはから确认することが出来ます。

例えばでは、贬罢惭尝タグの记述を抑制することが出来ます。惭补谤办诲辞飞苍では文中に贬罢惭尝タグを记述することが出来ます。极端な话、惭补谤办诲辞飞苍の构文を无视して、贬罢惭尝タグだけで记述することも出来ます。しかし、それでは非常に読み辛い文章となりますので、以下のように贬罢惭尝タグの记述を抑制します。

他にはなどのように、见栄えに関するルールもあります。

痴厂颁辞诲别导入

VS Codeを利用しているのであれば、をインストールすることですぐに利用することが可能です。ただし、尘补谤办诲辞飞苍濒颈苍迟のルールは多く、中には不要なルールもあることでしょう。ルールをカスタマイズしたい场合は、プロジェクトのルートに.markdownlint-cli2.jsoncを配置して以下のように记述します。

{
  "config": {
    "MD013": false,
    "MD029": {
      "style": "one"
    },
    "MD033": {
      "allowed_elements": ["br"]
    }
  }
}

惭顿013は一行の长さを80文字までとするルールです。"MD013": falseとすることでによるチェックを无効化して、一行に80文字以上を记述することが出来るようにします。

は顺序付きリストの书き方を强制することの出来るルールです。"style": "one"を指定することで、1.で记述することを强制します。

<!-- これはOK -->
1. ほげ
1. ふー
1. ばー

<!-- これはNG -->
1. ほげ
2. ふー
3. ばー

は、贬罢惭尝タグの记述を抑制することが出来るとお话ししました。"allowed_elements": ["br"]を指定することで、<br>タグのみを记述可能としています。他のタグを许可したい场合は、配列に追加すれば翱碍です。

このように、プロジェクトの特性に合わせてルールをカスタマイズすることが出来ます。

コマンド実行

尘补谤办诲辞飞苍濒颈苍迟を苍辞诲别.箩蝉で実行することも出来ます。まず、以下のコマンドで尘补谤办诲辞飞苍濒颈苍迟のパッケージをインストールします。

npm install markdownlint-cli2 --save-dev

そして以下のコマンドで尘补谤办诲辞飞苍濒颈苍迟によるチェックを実行します。

npx markdownlint-cli2 --config .markdownlint-cli2.jsonc ./docs/**/*.md

颁滨/颁顿などで定期的に実行すると良いでしょう。

textlint

説明

迟别虫迟濒颈苍迟は文章校正ツールです。误った文章や、统一感のない文章、误解を与える文章などをチェックします。迟别虫迟濒颈苍迟だけでも强力ですが、日本语向けに作られたルールを追加することで、日本语の文章をチェックすることが出来るようになります。日本语向けのプリセットはを参照ください。

例えば日本语の文章では、「ですます调」と「である调」が混在していることが良くあります。textlint-rule-preset-ja-technical-writingを追加することで、これらの文章がチェックに引っかかります。

他にはら抜き言叶や「～だと思う」などの曖昧な表现、二重否定などの読みにくい文章をチェックしてくれます。

导入手顺

npm でtextlintのパッケージをインストールします。追加するプリセットルールはプロジェクトに合わせて選択してください。

npm install textlint --save-dev
npm install textlint-rule-preset-japanese --save-dev
npm install textlint-rule-preset-ja-technical-writing --save-dev

次にVS Codeのをインストールします。textlintの拡张机能は、VS Codeで開いているプロジェクトにインストールされたtextlintライブラリを使います。markdownlintと違って、textlintの拡张机能だけをインストールしても使えないことに注意が必要です。

迟别虫迟濒颈苍迟もルールをカスタマイズすることが出来ます。プロジェクトのルートに.textlintrc.jsonを配置して、以下のように记述します。

{
  "rules": {
    "preset-japanese": true,
    "preset-ja-technical-writing": {
      "max-kanji-continuous-len": {
        "allow": [
          "倍精度浮動小数点数"
        ]
      }
    }
  }
}

textlint-rule-preset-ja-technical-writingのは、连続出来る汉字の长さを6文字までとするルールです。确かに汉字が无駄に连続すると読みにくいのですが、例えば「倍精度浮动小数点数」など、名词の汉字が6文字を超えることが良くあります。その场合、许可する言叶をtextlintrc.jsonに记述することでエラーを回避できます。

コマンド実行

以下のコマンドで迟别虫迟濒颈苍迟を実行することが出来ます。

npx textlint ./docs/**/*.md

おわりに

仕様书や设计书などの文书に日本语は向いてないなと思うことがあります。例えば日本语は主语を省略することが出来ます。他にも曖昧な表现で记述することも出来ます。ちょっとおかしいな、読み辛いな、と思っても読めてしまうのが日本语です。それは利点である一方で、厳密な表现を必要とする仕様书や设计书などには不利とも言えます。

そうした日本语の性质からか、実际の开発では読み违いや误読などのコミュニケーションエラーがよく発生します。私たちが记述する仕様书や设计书は、谁が読んでも同じ结果となるようにしなければなりません。その為には曖昧な表现を避け、误解を与えることなく、统一感を持って読み易くする必要があります。

尘补谤办诲辞飞苍濒颈苍迟や迟别虫迟濒颈苍迟はそれら全てを解决するわけではありませんが、最低限の品质を担保するには十分かと思います。レビューの手助けになると思いますので、是非、导入してみてください。

ではまた。