Open6
コメント・ルールについて🌟
ピン留めされたアイテム
まさぴょんコードコメントが有効な事例
コードコメントは必要なところに最小限に書くようにした方が良いです。
処理の全てに書く必要はなく、むしろ邪魔にもなります。
コメントが有用な例は:
- publicなfunctionとかのdoc comment
- 長い処理をparagraphに分けて、paragraphごとに目的を説明するコメント
- 名前から簡単に想定されないような処理についてのコメント
など。
逆に、冗長すぎるコメントは、、、
- 非常に典型的な処理を行っているコメント
- コードを少し読めば目的と処理内容がわかるコメント
など。
まさぴょんJavaScript/TypeScriptでのコメントについて
JSDoc
TypeDoc
JSDoc
TypeDoc
まさぴょんアノテーションコメントについて
- TODOなどの状態を端的に表すタグ的な役割のコメントのこと。
| 記法 | 説明 |
|---|---|
| TODO: | あとで追加、修正するべき機能がある。 |
| FIXME: | 既知の不具合があるコード。修正が必要。 |
| HACK: | あまりきれいじゃないコード。リファクタリングが必要。 |
| XXX: | 危険！動くけどなぜうごくかわからない。 |
| REVIEW: | 意図した通りに動くか、見直す必要がある。 |
| OPTIMIZE: | 無駄が多く、ボトルネックになっている。 |
| CHANGED: | コードをどのように変更したか。 |
| NOTE: | なぜ、こうなったという情報を残す。 |
| WARNING: | 注意が必要。 |
まさぴょんコメントとして、何を残すべきか？
プログラム内のコメントは、コードの理解を助け、将来のメンテナンスを容易にするために重要です。
次のようなポイントは重要
- 明確な目的:
- コメントはコードの目的を明確に説明する必要があります。
- これにより、他の開発者がコードの機能を迅速に理解し、必要に応じて適切に変更できます。
- 適切な場所:
- コメントは、その説明が必要なコードの直前や内部に配置することが最も効果的です。
- これにより、コードの特定の部分を理解しやすくなります。
- 簡潔さ:
- コメントは簡潔であるべきですが、必要な情報を省略しないように注意が必要です。
- 長すぎるコメントは読み飛ばされがちですが、短すぎるコメントでは情報が不足してしまいます。
- 維持の容易さ:
- コードが変更された場合、関連するコメントも更新する必要があります。
- 古いまたは関連性のないコメントは混乱を招く可能性があります。]
良いコメントの例としては、複雑なアルゴリズムの説明、コードが解決しようとしている特定の問題、変数や関数の目的、または特定のコード行が存在する理由が挙げられます。
これにより、コードの可読性が向上し、開発者間のコミュニケーションが促進されます。
まさぴょんVSCode拡張機能『Todo Tree』
This extension quickly searches (using ripgrep) your workspace for comment tags like TODO and FIXME, and displays them in a tree view in the activity bar.
The view can be dragged out of the activity bar into the explorer pane (or anywhere else you would prefer it to be).
Clicking a TODO within the tree will open the file and put the cursor on the line containing the TODO.
Found TODOs can also be highlighted in open files.
Please see the wiki for configuration examples.
JSDoc の記法内の TODO を拾えるように、設定を追加する
- JSDoc の記法内の TODO を拾えるように、setting.jsonに設定を追加する
setting.json
"todo-tree.regex.regex": "(//|#|<!--|/\\*|^\\s*\\*)\\s*($TAGS)"
設定例 Wiki
Repository
まさぴょんアノテーションコメントとTeam運用について