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

JAWS-UG CDK支部#19 クラスメソッドコラボ回で登壇したスライドです
https://jawsug-cdk.connpass.com/event/343974/

Transcript

1. 2025/02/21 山梨 蓮 JAWS-UG CDK支部#19 クラスメソッドコラボ回
2. 自己紹介 @ren_yamanashi ・job 󰞵: web engineer (backend) ・lang 📝: TypeScript ・hobby 🚀: CDK Contribute
3. 前提 ・JavaScript / TypeScriptを使用した開発を想定しています
4. 自己紹 介 コーディング規約とは？
5. コーディング規約 ・コーディングにおけるルール (e.g. Construct で公開する変数は readonly をつける) ・保守性が高く、一貫性のあるコードを保つ 　→複数人での開発ではコーディング規約の運用が重要
6. コーディング規約 ・コーディングにおけるルール (e.g. Construct で公開する変数は readonly をつける) ❌ 自前で運用 ・保守性が高く、一貫性のあるコードを保つ 　→複数人での開発ではコーディング規約の運用が重要
7. コーディング規約 ・コーディングにおけるルール (e.g. Construct で公開する変数は readonly をつける) ❌ 自前で運用 ・保守性が高く、一貫性のあるコードを保つ 　→複数人での開発ではコーディング規約の運用が重要 ⭕ Linter / Formatter を使用した運用
8. 課題 ・どのツールを使えばいいのか迷う 　(e.g. Linterは ESLint? Biome?) ・CDK開発特有のコーディング規約はどうする？
9. 課題 ・どのツールを使えばいいのか迷う 　(e.g. Linterは ESLint? Biome?) ・CDK開発特有のコーディング規約はどうする？ 目標：適切なツールの選定・コーディング規約の制定
10. 取り上げる内容 ・ Linterの選定 ・コードの規約に関する内容 ・コメントの規約に関する内容 ・JSDoc
11. 自己紹 介 コードの規約: Linterの選定
12. ・JS/TS などのコードを解析して、ルールに沿っているかをチェックするツール ・コーディング規約を定めて、それに沿っていないコードを修正・違反にする Linter とは？
13. Linter とは？ 🤔 どのLinterを使えばいいのか迷う (e.g. ESLint / Biome) ・JS/TS などのコードを解析して、ルールに沿っているかをチェックするツール ・コーディング規約を定めて、それに沿っていないコードを修正・違反にする
14. Linter とは？ →　それぞれの特徴などを正しく理解し、適切に選定する 🤔 どのLinterを使えばいいのか迷う (e.g. ESLint / Biome) ・JS/TS などのコードを解析して、ルールに沿っているかをチェックするツール ・コーディング規約を定めて、それに沿っていないコードを修正・違反にする
15. ① ESLint ② Biome ③ Oxlint
16. ① ESLint ② Biome ③ Oxlint
17. ・プラグイン(typescript-eslint)でTSをサポート ① ESLint ・有名なJSのLinter ・設定ファイル(eslint.config.js)の記述が必要 ・プラグインが豊富 / 自前でカスタムルールを作れる ・型情報を用いたLintルールが提供される(typescript-eslint)
18. ・プラグイン(typescript-eslint)でTSをサポート ① ESLint ・JSのLinterとして有名 ・設定ファイル(eslint.config.js)の記述が必要 ・プラグインが豊富 / 自前でカスタムルールを作れる ・型情報を用いたLintルールが提供される(typescript-eslint)
19. 型情報Lintルールの例 ・switch-exhaustiveness-check
20. ・プラグイン(typescript-eslint)でTSをサポート ① ESLint ・JSのLinterとして有名 ・設定ファイル(eslint.config.js)の記述が必要 ・プラグインが豊富 / 自前でカスタムルールを作れる ・型情報を用いたLintルールが提供される(typescript-eslint) TypeScript Compiler に依存してLintを行なっている
21. ① ESLint ② Biome ③ Oxlint
22. ・ESLintに比べて速い(15倍) ② Biome ・Rust製のLinter (Formatterなども提供) ・Webで使われる技術(JS/TS/CSS/JSON)をサポート ・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない
23. ・ESLintに比べて速い(15倍) ② Biome ・Rust製のLinter (Formatterなども提供) ・Webで使われる技術(JS/TS/CSS/JSON)をサポート ・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない
24. ・ESLintに比べて速い(15倍) ② Biome ・Rust製のLinter (Formatterなども提供) ・Webで使われる技術(JS/TS/CSS/JSON)をサポート ・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない TypeScript Compiler に依存していない (パフォーマンス面の懸念)
25. ① ESLint ② Biome ③ Oxlint
26. ・ESLintに比べて速い(50~100倍) ③ Oxlint (Oxc) ・Rust製のLinter ・JS/TSを対象 ・設定ファイルの記述なしでも動作する(no config) ・型情報のLintルールがない ・ESLintや他のPluginとの互換性を意識 (ESLintの完全置き換えではなく、ESLintを補う)
27. ③ Oxlint （Oxc） ESLintや他のPluginとの互換性を意識 → ESLintの完全置き換えではなく、速度面でESLintを補う
29. 自己紹 介 CDKでは何を使う？
30. 何がいいか？ 個人的には・・・ ・まだESLint(typescript-eslint) ・速度が気になる場合は、Oxlintとの併用も ・型情報Lintルールは取り入れたい ・プラグインの豊富さ・カスタムルールが作成可能 （自分でルールが作れる選択肢は残しておきたい）
31. 自己紹 介 コメントの規約: JSDoc
32. JSDocとは？
33. オプショナルなプロパティがある場合・・・ ・指定しない場合はどのようなデフォルト値がリソースに設定されるのか CDKでの活用例 具体的な実装を見ることなく理解できる
34. 自己紹 介 CDK開発における “JSDocの規約”
35. CDK開発でのJSDocに関する規約 個人的には・・・ ・interfaceのプロパティ・Constructで公開するプロパティにはJSDocを必須に ・オプショナルなプロパティには必ず @default を記述する より明確で使いやすく、可読性の高いConstructに (aws-cdk/packages/awslint/lib/rules/docs.tsでも実装されている)
36. まとめ ・CDK開発におけるコーディング規約の運用を解説 ・Linter ・JSDoc JSDocに関するルール・CDK独自のルールは、 “eslint-cdk-plugin” で提供されているので、ぜひ使ってみてください！！ ・とりあえずESLint ・interface・Constructのpublic変数にはJSDocを必須に ・オプショナルなプロパティには必ず @default を記述