CDK開発におけるコーディング規約の運用

Slide 1

Slide 1 text

2025/02/21 山梨蓮 JAWS-UG CDK支部#19 クラスメソッドコラボ回

Slide 2

Slide 2 text

自己紹介 @ren_yamanashi ・job 󰞵: web engineer (backend) ・lang 📝: TypeScript ・hobby 🚀: CDK Contribute

Slide 3

Slide 3 text

前提・JavaScript / TypeScriptを使用した開発を想定しています

Slide 4

Slide 4 text

自己紹介コーディング規約とは？

Slide 5

Slide 5 text

コーディング規約・コーディングにおけるルール (e.g. Construct で公開する変数は readonly をつける) ・保守性が高く、一貫性のあるコードを保つ　→複数人での開発ではコーディング規約の運用が重要

Slide 6

Slide 6 text

コーディング規約・コーディングにおけるルール (e.g. Construct で公開する変数は readonly をつける) ❌ 自前で運用・保守性が高く、一貫性のあるコードを保つ　→複数人での開発ではコーディング規約の運用が重要

Slide 7

Slide 7 text

コーディング規約・コーディングにおけるルール (e.g. Construct で公開する変数は readonly をつける) ❌ 自前で運用・保守性が高く、一貫性のあるコードを保つ　→複数人での開発ではコーディング規約の運用が重要 ⭕ Linter / Formatter を使用した運用

Slide 8

Slide 8 text

課題・どのツールを使えばいいのか迷う　(e.g. Linterは ESLint? Biome?) ・CDK開発特有のコーディング規約はどうする？

Slide 9

Slide 9 text

課題・どのツールを使えばいいのか迷う　(e.g. Linterは ESLint? Biome?) ・CDK開発特有のコーディング規約はどうする？目標：適切なツールの選定・コーディング規約の制定

Slide 10

Slide 10 text

取り上げる内容・ Linterの選定・コードの規約に関する内容・コメントの規約に関する内容・JSDoc

Slide 11

Slide 11 text

自己紹介コードの規約: Linterの選定

Slide 12

Slide 12 text

・JS/TS などのコードを解析して、ルールに沿っているかをチェックするツール・コーディング規約を定めて、それに沿っていないコードを修正・違反にする Linter とは？

Slide 13

Slide 13 text

Linter とは？ 🤔 どのLinterを使えばいいのか迷う (e.g. ESLint / Biome) ・JS/TS などのコードを解析して、ルールに沿っているかをチェックするツール・コーディング規約を定めて、それに沿っていないコードを修正・違反にする

Slide 14

Slide 14 text

Linter とは？ →　それぞれの特徴などを正しく理解し、適切に選定する 🤔 どのLinterを使えばいいのか迷う (e.g. ESLint / Biome) ・JS/TS などのコードを解析して、ルールに沿っているかをチェックするツール・コーディング規約を定めて、それに沿っていないコードを修正・違反にする

Slide 15

Slide 15 text

① ESLint ② Biome ③ Oxlint

Slide 16

Slide 16 text

① ESLint ② Biome ③ Oxlint

Slide 17

Slide 17 text

・プラグイン(typescript-eslint)でTSをサポート ① ESLint ・有名なJSのLinter ・設定ファイル(eslint.config.js)の記述が必要・プラグインが豊富 / 自前でカスタムルールを作れる・型情報を用いたLintルールが提供される(typescript-eslint)

Slide 18

Slide 18 text

・プラグイン(typescript-eslint)でTSをサポート ① ESLint ・JSのLinterとして有名・設定ファイル(eslint.config.js)の記述が必要・プラグインが豊富 / 自前でカスタムルールを作れる・型情報を用いたLintルールが提供される(typescript-eslint)

Slide 19

Slide 19 text

型情報Lintルールの例・switch-exhaustiveness-check

Slide 20

Slide 20 text

Slide 21

Slide 21 text

① ESLint ② Biome ③ Oxlint

Slide 22

Slide 22 text

・ESLintに比べて速い(15倍) ② Biome ・Rust製のLinter (Formatterなども提供) ・Webで使われる技術(JS/TS/CSS/JSON)をサポート・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない

Slide 23

Slide 23 text

Slide 24

Slide 24 text

・ESLintに比べて速い(15倍) ② Biome ・Rust製のLinter (Formatterなども提供) ・Webで使われる技術(JS/TS/CSS/JSON)をサポート・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない TypeScript Compiler に依存していない (パフォーマンス面の懸念)

Slide 25

Slide 25 text

① ESLint ② Biome ③ Oxlint

Slide 26

Slide 26 text

・ESLintに比べて速い(50~100倍) ③ Oxlint (Oxc) ・Rust製のLinter ・JS/TSを対象・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない・ESLintや他のPluginとの互換性を意識 (ESLintの完全置き換えではなく、ESLintを補う)

Slide 27

Slide 27 text

③ Oxlint （Oxc） ESLintや他のPluginとの互換性を意識 → ESLintの完全置き換えではなく、速度面でESLintを補う

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

自己紹介 CDKでは何を使う？

Slide 30

Slide 30 text

何がいいか？個人的には・・・・まだESLint(typescript-eslint) ・速度が気になる場合は、Oxlintとの併用も・型情報Lintルールは取り入れたい・プラグインの豊富さ・カスタムルールが作成可能（自分でルールが作れる選択肢は残しておきたい）

Slide 31

Slide 31 text

自己紹介コメントの規約: JSDoc

Slide 32

Slide 32 text

JSDocとは？

Slide 33

Slide 33 text

オプショナルなプロパティがある場合・・・・指定しない場合はどのようなデフォルト値がリソースに設定されるのか CDKでの活用例具体的な実装を見ることなく理解できる

Slide 34

Slide 34 text

自己紹介 CDK開発における “JSDocの規約”

Slide 35

Slide 35 text

CDK開発でのJSDocに関する規約個人的には・・・・interfaceのプロパティ・Constructで公開するプロパティにはJSDocを必須に・オプショナルなプロパティには必ず @default を記述するより明確で使いやすく、可読性の高いConstructに (aws-cdk/packages/awslint/lib/rules/docs.tsでも実装されている)

Slide 36

Slide 36 text

まとめ・CDK開発におけるコーディング規約の運用を解説・Linter ・JSDoc JSDocに関するルール・CDK独自のルールは、 “eslint-cdk-plugin” で提供されているので、ぜひ使ってみてください！！・とりあえずESLint ・interface・Constructのpublic変数にはJSDocを必須に・オプショナルなプロパティには必ず @default を記述