163 lines
5.6 KiB
Markdown
163 lines
5.6 KiB
Markdown
---
|
||
description: 'GitHub Copilotが自説明的なコードでコメントを少なくするためのコメント記述ガイドライン。例はJavaScriptだが、コメントを持つあらゆる言語で動作する。'
|
||
applyTo: '**'
|
||
---
|
||
|
||
# 自説明的コードコメント指示事項
|
||
|
||
## 核心原則
|
||
**コード自体が語るように書く。「なぜ」を説明する必要がある場合のみコメントする。「何を」ではない。**
|
||
ほとんどの場合、コメントは必要ありません。
|
||
|
||
## コメントガイドライン
|
||
|
||
### ❌ 避けるべきコメント種類
|
||
|
||
**自明なコメント**
|
||
```javascript
|
||
// Bad: 自明なことを述べる
|
||
let counter = 0; // カウンターをゼロに初期化
|
||
counter++; // カウンターを1増加
|
||
```
|
||
|
||
**冗長なコメント**
|
||
```javascript
|
||
// Bad: コメントがコードを繰り返している
|
||
function getUserName() {
|
||
return user.name; // ユーザーの名前を返す
|
||
}
|
||
```
|
||
|
||
**古いコメント**
|
||
```javascript
|
||
// Bad: コメントがコードと一致しない
|
||
// 5%の税率で計算
|
||
const tax = price * 0.08; // 実際は8%
|
||
```
|
||
|
||
### ✅ 記述すべきコメント種類
|
||
|
||
**複雑なビジネスロジック**
|
||
```javascript
|
||
// Good: なぜこの特定の計算をするのかを説明
|
||
// 累進税制を適用: 10万円まで10%、それ以上20%
|
||
const tax = calculateProgressiveTax(income, [0.10, 0.20], [100000]);
|
||
```
|
||
|
||
**自明でないアルゴリズム**
|
||
```javascript
|
||
// Good: アルゴリズム選択の説明
|
||
// すべてのノード間の距離が必要なため
|
||
// Floyd-Warshall法を使用してすべてのペアの最短経路を求める
|
||
for (let k = 0; k < vertices; k++) {
|
||
for (let i = 0; i < vertices; i++) {
|
||
for (let j = 0; j < vertices; j++) {
|
||
// ... 実装
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**正規表現パターン**
|
||
```javascript
|
||
// Good: 正規表現が何にマッチするかを説明
|
||
// メール形式にマッチ: ユーザー名@ドメイン.拡張子
|
||
const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
|
||
```
|
||
|
||
**API制約や注意事項**
|
||
```javascript
|
||
// Good: 外部制約を説明
|
||
// GitHub API レート制限: 認証ユーザーは5000リクエスト/時間
|
||
await rateLimiter.wait();
|
||
const response = await fetch(githubApiUrl);
|
||
```
|
||
|
||
## 判断フレームワーク
|
||
|
||
コメントを書く前に自問：
|
||
1. **コードは自説明的か？** → コメント不要
|
||
2. **より良い変数名・関数名で必要性を解消できるか？** → 代わりにリファクタリング
|
||
3. **これは「何を」でなく「なぜ」を説明しているか？** → 良いコメント
|
||
4. **これは将来のメンテナーに役立つか？** → 良いコメント
|
||
|
||
## コメントの特別なケース
|
||
|
||
### パブリックAPI
|
||
```javascript
|
||
/**
|
||
* 標準公式を使用して複利を計算する。
|
||
*
|
||
* @param {number} principal - 初期投資額
|
||
* @param {number} rate - 年間金利（小数、例：5%の場合0.05）
|
||
* @param {number} time - 期間（年）
|
||
* @param {number} compoundFrequency - 年間複利回数（デフォルト: 1）
|
||
* @returns {number} 複利計算後の最終額
|
||
*/
|
||
function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
|
||
// ... 実装
|
||
}
|
||
```
|
||
|
||
### 設定と定数
|
||
```javascript
|
||
// Good: ソースや理由を説明
|
||
const MAX_RETRIES = 3; // ネットワーク信頼性調査に基づく
|
||
const API_TIMEOUT = 5000; // AWS Lambdaタイムアウトは15秒、バッファを残す
|
||
```
|
||
|
||
### アノテーション
|
||
```javascript
|
||
// TODO: セキュリティレビュー後に適切なユーザー認証に置き換え
|
||
// FIXME: 本番環境でメモリリーク - コネクションプールを調査
|
||
// HACK: ライブラリv2.1.0のバグの回避策 - アップグレード後に削除
|
||
// NOTE: この実装はすべての計算でUTCタイムゾーンを想定
|
||
// WARNING: この関数はコピーを作成する代わりに元の配列を変更
|
||
// PERF: ホットパスで頻繁に呼ばれる場合はこの結果をキャッシュすることを検討
|
||
// SECURITY: クエリで使用する前にSQLインジェクションを防ぐため入力を検証
|
||
// BUG: 配列が空の場合のエッジケース失敗 - 調査が必要
|
||
// REFACTOR: 再利用のためにこのロジックを別のユーティリティ関数に抽出
|
||
// DEPRECATED: 代わりにnewApiFunction()を使用 - これはv3.0で削除予定
|
||
```
|
||
|
||
## 避けるべきアンチパターン
|
||
|
||
### デッドコードコメント
|
||
```javascript
|
||
// Bad: コードをコメントアウトしない
|
||
// const oldFunction = () => { ... };
|
||
const newFunction = () => { ... };
|
||
```
|
||
|
||
### 変更履歴コメント
|
||
```javascript
|
||
// Bad: コメントで履歴を維持しない
|
||
// 2023-01-15にJohnが変更
|
||
// 2023-02-03にSarahが報告したバグを修正
|
||
function processData() {
|
||
// ... 実装
|
||
}
|
||
```
|
||
|
||
### 仕切りコメント
|
||
```javascript
|
||
// Bad: 装飾的なコメントを使用しない
|
||
//=====================================
|
||
// ユーティリティ関数
|
||
//=====================================
|
||
```
|
||
|
||
## 品質チェックリスト
|
||
|
||
コミット前に、コメントが以下を満たすことを確認：
|
||
- [ ] 「何を」でなく「なぜ」を説明している
|
||
- [ ] 文法的に正しく明確である
|
||
- [ ] コードが進化しても正確であり続ける
|
||
- [ ] コード理解に真の価値を追加している
|
||
- [ ] 適切な場所（説明するコードの上）に配置されている
|
||
- [ ] 適切なスペルとプロフェッショナルな言語を使用している
|
||
|
||
## まとめ
|
||
|
||
覚えておいてください：**最高のコメントは、コードが自己文書化されているため書く必要がないものです。**
|