どのように効率的に保守コードを書くには？

メモは、コード内の見当違いと役に立たないが、非常に興味深いものではありません見つけますか？どのようにいくつかのコメントを書きますが、まだ理解し、コードをより簡単にしますか？

一つの主要な方法は、コードの自己文書を作ることです。あなたがその役割や目的にコメントする必要があり、また維持するために、コードがはるかに容易になりますしないときのコードは、自己文書化された場合。

この記事では、私はあなたのコードの自己文書化の方法を作るために提供されます。このような基本的なメソッドコードの以下の3種類は、自己文書化です。

命名：変数、関数、および名前のように利用目的を説明します。
ラッパー関数：特定のコードの機能は明確な目的の関数にカプセル化されます。
変数が導入された：式は、プライベート変数に挿入されています。

これは、単純なように見えるかもしれないが、実際の動作中の人は少しトリッキーな感じになります。まず、あなたはどのような問題領域と、該当する場合、これらの方法のどれを理解する必要があります。これら三つのに加えて、そこには方法で広く使用されています。

クラスとモジュールインタフェース：機能とモジュールのクラスが公開され、コードをより明確にします。
コードグループ：異なるセグメントを区別するためのコードのグループ。

次に我々は、一例として実用的なアプリケーションでは5つのメソッドを使用する方法について話を具体的になります。

名前の一つ、

まず、コードネームが明らかになったと自己文書化の例どのようにいくつかの使用を見てください。

次のルールを遵守できる機能の名前を変更します。

handleLinks、manageObjects - 「管理」「ハンドル」などあいまいな言葉を使用しないでください。
積極的に実行される機能を示すためにcutGrass、SENDFILE、 - アクティブな動詞を使用してください。
getMagicBullet、READFILE - 戻り値のタイプを指定します。強く機能タイプ識別子の戻り値の型を示すために、言語を入力することができます。

変数の名前を変更します。

指定された単位 - 数値パラメータがある場合、それはユニットと組み合わせることができます。例えば、代わりにピクセル単位で指定された幅にwidthPx幅を使用します。
ショートカットキーを使用しないでください - a、bはパラメータ名として使用することはできません。

第二に、機能パッケージ

次に、コードは関数にカプセル化された方法のいくつかの例を見てください。カプセル化の利点の1つは、コードの重複機能を避ける構造やコードを改善することです。

機能コードの中にカプセル化されました。

これは最も基本的なものです。その目的を明確にするために機能コードにカプセル化。このコード行をやっていると思います。

var width = (value - 0.5) * 16;

非常に明確で、当然のことながら、鮮明な画像のコメントがありますが、以下のように、我々は、自己文書化を達成するために、関数にパッケージ化することができないようです。

var width = emToPixels(value);

function emToPixels(ems) {
    return (ems - 0.5) * 16;
}

唯一の変更は、計算プロセスが内部機能に移しています。この名前は明らかにそれを行うために必要なもの、そのような行動は、コメントを記述する必要はない表現しました。そこには、後で必要にされている場合また、あなたはまた、作業の重複を減らすために、2つの目的があり、この関数を直接呼び出すことができます。

条件式の代わりの機能を使用して。

声明は、それが複数のオペランドが含まれている場合ならば、それはより困難であることを意味するとのコメントを書いてはいけません。

if(!el.offsetWidth || !el.offsetHeight) {
}

このコードの目的は、上記ではありません知っていますか？それがないように置き換え：

function isVisible(el) {
    return el.offsetWidth && el.offsetHeight;
}

if(!isVisible(el)) {
}

変数の第三に、導入

最後に、変数を導入する方法について話しています。上記の二つの方法に比べて、これは私は知らないよりもよく知っている、とにかく、それほど有用ではないかもしれません。

代わりに、変数を持つ式の。

次の例を考えてみます。

if(!el.offsetWidth || !el.offsetHeight) {
}

これは、パッケージの機能は、変数の導入によって置き換えられないです。

var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}

代わりに、変数と方程式の。

また、明確に複雑なプログラムを説明するために使用することができます。

return a * b + (c / d);

代わりに変数を使用しました：

var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;

四、クラスおよびインタフェースモジュール

インターフェースクラスとモジュール - ドキュメントを使用する方法のようなビット - また、パブリックメソッドとプロパティの。以下の例を参照してください。

class Box {
   public function setState(state) {
       this.state = state;
   }
   public function getState() {
       return this.state;
   }
}

また、このクラスは、他のコードを含めることができます。私は意図的にどのように共通のインターフェース自己文書を示すために、この例を引用します。あなたはそれが呼ばれる方法です。このクラスに名前を付けることはできますか？明らかに、これは明らかにされていません。

これらの機能の両方が彼らの正当な目的を表現するために名前を変更する必要があります。しかし、たとえこれを行うために、我々はまだどのように使用することは非常に明確ではありません。そして、あなたはより多くのコードを読んだり、ドキュメントを読む必要があります。しかし、我々は、これは少し変更した場合は？

class Box {
    public function open() {
        this.state = open;
    }

    public function close() {
        this.state = closed;
    }

    public function isOpen() {
        return this.state == open;
    }
}

それは、より明確ではないですか？我々は唯一のパブリックインターフェイス、元の内部表現に変更ことに注意してくださいthis.state同じの状態を。

第五に、コードパケット

コードの一の形態設定の異なる部分を区別するために使用される自己文書化されています。記事が言ったように、例えば、我々はそれを使用するために可能な限り近い変数を定義し、可能な限り変数カテゴリ必要があります。これはまた、異なるコードグループとの間の関係を指定するために使用することができるので、より便利に他の人は、彼らがコードグループを知るために必要なものを知っています。以下の例を参照してください。

var foo = 1;

blah()
xyz();

bar(foo);
baz(1337);
quux(foo);

以下と比較すると：

var foo = 1;
bar(foo);
quux(foo);

blah()
xyz();

baz(1337);

ウィルfooすべての使用の組み合わせが一緒に入れ、一目見ただけで、あなたは関係のすべての種類を知ることができます。しかし、時には、私たちは途中でいくつかの他の関数を呼び出す必要があります。あなたがいない場合は、コードのグループ化を使用しようとすることができそうだとすれば、その主張はありません。

他の6つの提言

奇妙なマークを使用しないでください、以下の二つは等価です：

imTricky && doMagic();
if(imTricky) {
    doMagic();
}

明らかに後者の方が良いです。文法のスキルと何か良いをしませんでした。

定数名前付き：いくつかの特別な価値があるコードならば、それは彼らのような名前を与えることが最善ですvar PURPOSE_OF_LIFE = 42。

ルール：人々は他のコードを参照して、物事の様々な意味を推測正しく読み取ることができますので、同じ命名規則に従うことが最善。

転載元https://colobu.com/2014/12/23/How-to-make-your-code-self-documenting/

英文原文 http://codeutopia.net/blog/2014/12/01/how-to-make-your-code-self-documenting/

ます。https：//www.jianshu.com/p/f55a8fdc6024で再現