はじめに
- 必要ない場合はメモを追加しないでください。
// bad
// データが準備されている場合...
if (data && data.status === 'ready') {
...
}
// good
const isDataReady = data && data.status === 'ready';
if (isDataReady) {
...
}
- 必要であれば、できるだけ詳しく
コードは方法を説明することはできますが、理由を説明することはできません。
悪いアノテーション
- アノテーションはコードを読むのに役に立ちません。
- 継続的に管理されていないノート
// bad 注釈が長すぎて、読む気にならない。
/**
* Convert an input value to a number for persistence.If the conversion fails, return original string.
*/
function toNumber (val) {
...
}
// good
/**
* Convert an input value to a number for persistence.
* If the conversion fails, return original string.
*/
function toNumber (val) {
...
}
- 感情的注釈：愚痴、差別、癖など。
/**
* このプロジェクトは非常に悪い、バグが多い！
*/
良いアノテーション
- 何のために？
このコードを書いた動機、考えていたこと、アルゴリズム固有のロジックを書くことができます。
/**
* Convert an input value to a number for persistence.
* If the conversion fails, return original string.
*/
function toNumber (val) {
...
}
- 特殊な処方や理解しにくい処方についての説明文
例えばRegExpの長いパラグラフ、ここで何が起こっているのか理解できますか？それとも数年経ってもすぐに理解できますか？
// アノテーションは、"|"が2になる回数を"|"太字と下線の内容の間にある
const reg = new RegExp("([^\\|]*)(\\|)([^\\|]*)(\\|)([^\\|]*)", "ig");
また、常にコードを改善する必要があり、ここでは、この段落の欠陥を上げるために特別な注釈TODOを付けることができます。よく使われる特別な注釈は2つあります：
- // FIXME: 問題の説明
- // FIXME: 問題点の説明
- あなたにとっては明確で理解できることでも、他の人にとってはそうではないかもしれません。
- 本の章のような注釈
- 文書クラスノート
APIやクラス、関数などがドキュメントクラスのアノテーションを使用することが合意されることがあります。
良いコメントの書き方
アノテーションの規約
宣言変数は宣言の後に置くことをお勧めします。
vm._vnode = null; // the root of the child tree
// bad
// the root of the child tree
vm._vnode = null;
// v-once cached trees
vm._staticTrees = null;
// good
// the root of the child tree
vm._vnode = null;
// v-once cached trees
vm._staticTrees = null;
// good
// ブロックの先頭のコメント行は空行を必要としない
function setVNode(node) {
// the root of the child tree
vm._vnode = node;
}
// bad
// Convert an input value to a number for persistence.
// If the conversion fails, return original string.
function toNumber (val) {
...
}
// good
/**
* Convert an input value to a number for persistence.
* If the conversion fails, return original string.
*/
function toNumber (val) {
...
}
// bad
//the root of the child tree
vm._vnode = null;
// good
// the root of the child tree
vm._vnode = null;
// bad
/**
*Convert an input value to a number for persistence.
*If the conversion fails, return original string.
*/
function toNumber (val) {
...
}
// good
/**
* Convert an input value to a number for persistence.
* If the conversion fails, return original string.
*/
function toNumber (val) {
...
}
- jsdoc仕様を使用して、関数、クラス、ファイル、イベントなど、ドキュメントのようなアノテーションを使用します。
対のコードは、プラグインkorofileheader、jsdocを使用して自動的に追加することができます。
/**
* ブリッジ情報を設定する
* @param {*} bridge
*/
function setBridge(bridge) {
this.bridge=bridge;
}
ツール
Eslint
ESLintは現在最も人気のあるJSコードチェックツールです。 ESLintには注釈に関連するルールがいくつかあり、ユーザはそれをオンにすることができます。
- ドキュメントクラスのアノテーション
- require-jsdoc
Sonar
Sonarは、プロジェクトの注釈率データを取得するためにコードの静的スキャンを実行するコード継続的統合プラットフォームです。
アノテーション率は、全コード行に占めるアノテーション行の割合を表します。 アノテーション率が低すぎるのはよくありませんが、やみくもにアノテーション率の高さを追求すべきではありません。
