人々が読むことができるコードを書くことの重要性

コードを再度調べる必要がないときに、一気にプロジェクトを完了する必要がありましたか？ ほとんどない。 古いプロジェクトで作業する場合、このコードがどのように機能するかを理解するのに時間を無駄にしたくないでしょう。 コードが読みやすい場合は、製品のメンテナンスが容易であり、あなた、同僚、または従業員は満足しています。



判読不能なコードの鮮明な例はJS1kコンテストにあります。その目的は、1024文字以下で構成される最高のJSアプリケーションを作成することです。 JSF * ckについても同じことが言えます。JSF* ckは、6つの異なる文字のみを使用してJSコードを記述する非常に独特なプログラミングスタイルです。 これらのサイトに投稿されたコードを見て、ここで何が起こっているのかを理解しようとして頭を悩ますでしょう。 同様のコードを記述し、1か月後にバグを修正しようとするとどうなるか想像してみてください。



定期的にネットサーフィンをしたり、インターフェイスを作成したりする場合、すべてのユーザーが必要とするわけではない大きなフォームに記入するのに多くの時間と忍耐が必要であることをご存じでしょう。 コードについても同じことが言えます。 読みやすくなればなるほど、それを長時間使用するのが楽しくなります。 または、少なくともコンピューターを窓の外に放り出したいという欲求はありません。



この記事では、落とし穴を避けてコードを読みやすくするためのさまざまなトリックとトリックを取り上げます。



もとの記事： https : //www.sitepoint.com/importance-of-code-that-humans-can-read/

コード分​​離

フォームとの類似性に戻ります：画面に表示しやすくするために、フォームを部分に分割する場合があります。 同じことをコードで行うことができます。 部分に分割すると、ジャングルを通過することなく目的のフラグメントを見つけやすくなります。

ファイルの最適化

私たちは何年もの間ウェブの最適化を行ってきましたが、JSファイルも例外ではありません。 HTTP / 2を待っている間にミニファイを行うことで、複数のスクリプトを1つに結合してリクエストを保存しました。 今日では、ファイルを処理するタスクをGulpやGruntなどのツールに任せて、好きなように作業できます。 つまり、必要に応じてプログラムを作成し、特別に訓練されたアプリケーションに最適化（たとえば、連結の実行）を実行させることができます。

//     API var getUsersRequest = new XMLHttpRequest(); getUsersRequest.open('GET', '/api/users', true); getUsersRequest.addEventListener('load', function() { //  -   }); getUsersRequest.send(); //--------------------------------------------------- //    . // ,       . //--------------------------------------------------- //      API var getPostsRequest = new XMLHttpRequest(); getPostsRequest.open('GET', '/api/posts', true); getPostsRequest.addEventListener('load', function() { //  -   }); getPostsRequest.send();
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

機能

再利用可能なコードのブロックを作成できます。 通常、関数の内容により、関数の開始点と終了点を簡単に理解できます。 小さな関数を書くのは良い習慣です-10行以内。 関数の名前が正しい場合、呼び出されたときに何をするかを簡単に理解できます。 以下では、命名規則に戻ります。

 //     API function getUsers(callback) { var getUsersRequest = new XMLHttpRequest(); getUsersRequest.open('GET', '/api/users', true); getUsersRequest.addEventListener('load', function() { callback(JSON.parse(getUsersRequest.responseText)); }); getUsersRequest.send(); } //      API function getPosts(callback) { var getPostsRequest = new XMLHttpRequest(); getPostsRequest.open('GET', '/api/posts', true); getPostsRequest.addEventListener('load', function() { callback(JSON.parse(getPostsRequest.responseText)); }); getPostsRequest.send(); } //        //     getUsers(function(users) { //  -   }); getPosts(function(posts) { //  -   });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

上記のコードは読みやすいです。 両方の機能はほぼ同じであることに注意してください。 「 繰り返さない 」という原則に従うことができます。これにより、コード内の順序を維持できます。

 function fetchJson(url, callback) { var request = new XMLHttpRequest(); request.open('GET', url, true); request.addEventListener('load', function() { callback(JSON.parse(request.responseText)); }); request.send(); } //       //     fetchJson('/api/users', function(users) { //  -   }); fetchJson('/api/posts', function(posts) { //  -   });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

しかし、POST要求を使用して新しいユーザーを作成する場合はどうでしょうか。 次の2つのオプションがあります。

• 関数にオプションの引数を追加して、新しいロジックを導入し、関数を複雑にします。
• POSTリクエスト専用の新しい関数を作成します。これにより、コードが重複する可能性があります。

しかし、オブジェクト指向プログラミングのおかげで、構成可能なワンタイムオブジェクトを作成することにより、両方のオプションを最大限に活用できますが、コードの保守はかなり簡単です。

注 ：オブジェクト指向JavaScriptの基本だけが必要な場合は、次のビデオをご覧ください ：オブジェクト指向JavaScript の完全なガイド 。

オブジェクト指向プログラミング

しばしばクラスと呼ばれる、コンテキスト依存の関数のクラスターであるオブジェクトを検討してください。 このようなオブジェクトは、別のファイルに完全に収まります。 この場合、XMLHttpRequestの基本的なラッパーを作成できます。 2015年まで、JavaScriptはプロトタイプ指向の言語であり、クラスがなかったことに注意してください。 この事実は、プロトタイプの継承とともに、コードのフォーマットに関する特定の規則を規定しています。



HttpRequest.js

 function HttpRequest(url) { this.request = new XMLHttpRequest(); this.body = undefined; this.method = HttpRequest.METHOD_GET; this.url = url; this.responseParser = undefined; } HttpRequest.METHOD_GET = 'GET'; HttpRequest.METHOD_POST = 'POST'; HttpRequest.prototype.setMethod = function(method) { this.method = method; return this; }; HttpRequest.prototype.setBody = function(body) { if (typeof body === 'object') { body = JSON.stringify(body); } this.body = body; return this; }; HttpRequest.prototype.setResponseParser = function(responseParser) { if (typeof responseParser !== 'function') return; this.responseParser = responseParser; return this; }; HttpRequest.prototype.send = function(callback) { this.request.addEventListener('load', function() { if (this.responseParser) { callback(this.responseParser(this.request.responseText)); } else { callback(this.request.responseText); } }, false); this.request.open(this.method, this.url, true); this.request.send(this.body); return this; };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

app.js

 new HttpRequest('/users') .setResponseParser(JSON.parse) .send(function(users) { //  -   }); new HttpRequest('/posts') .setResponseParser(JSON.parse) .send(function(posts) { //  -   }); //    new HttpRequest('/user') .setMethod(HttpRequest.METHOD_POST) .setBody({ name: 'Tim', email: 'info@example.com' }) .setResponseParser(JSON.parse) .send(function(user) { //  -    });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

定数は、コンストラクターですぐに宣言する必要があることに注意してください。 上記で作成したHttpRequestクラスは、多くのAPI呼び出しを使用して広範囲に設定できるようになりました。 その実装（メソッド呼び出しのチェーン）がより複雑であることが判明したという事実にもかかわらず、クラス自体の保守は簡単です。 実装とコードを再利用する能力とのバランスを見つけるプロセスは困難な場合があり、プロジェクトによって異なります。



オブジェクト指向プログラミングへの大きな追加は、デザインパターンです。 それ自体では、読みやすさは向上しませんが、一貫性はそれを実現します！

人に優しい構文

ファイル、関数、オブジェクト-これらは単なる大まかなガイドラインです。 コードを簡単にスキャンできます。 しかし、コードを読みやすくすることは、はるかに微妙な技術です。 細部を細かくすることで、画像を完全に変更できます。 たとえば、多くの場合、垂直線を使用するエディターでは、行の長さは80文字に制限されています。 しかし、他にも多くのニュアンスがあります！

命名

適切な命名のおかげで、変数の種類やこの関数の機能を理解することなく、特定の要素を即座に認識することができます。



関数は通常、ラクダのスタイルで呼び出されます。最初に動詞、次に主語が来ます。

 function getApiUrl() { /* ... */ } function setRequestMethod() { /* ... */ } function findItemsById(n) { /* ... */ } function hideSearchForm() { /* ... */ }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

変数名については、 逆ピラミッド手法を使用してみてください。最初に件名が表示され、次にプロパティが表示されます。

 var element = document.getElementById('body'), elementChildren = element.children, elementChildrenCount = elementChildren.length; //   ,      “color” var colorBackground = 0xFAFAFA, colorPrimary = 0x663399; //   ,     “background” var backgroundColor = 0xFAFAFA, backgroundImages = ['foo.png', 'bar.png']; //     var headerBackgroundColor = 0xFAFAFA, headerTextColor = 0x663399;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そのような場合、連想配列（JSのオブジェクト）を使用する方が適切です。その後、色の接頭辞を取り除くことができ、読みやすさが向上します。

 var colors = { 'backgroundRed' : red, 'primary': greeen };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

また、通常の変数と特殊変数の区別を強調することも重要です。 たとえば、定数名は多くの場合アンダースコアで大文字になります。

 var URI_ROOT = window.location.href;     ,   . function FooObject { // ... }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

略語では、ニュアンスもあります。 誰かが大文字でのみ、キャメルスタイルで誰かを書いています。 前者の場合、略語を認識するのが難しい場合があります。



しかし、一般に、すべては開発者またはチームが採用したコーディングスタイルに依存します。 常に選択された1つのスタイルを順守し、そのコンプライアンスを確認し、リンターを使用する必要があります。

コンパクトで最適化

多くのコードベースでは、文字数を減らしたり、アルゴリズムのパフォーマンスを向上させるように設計された「特別な」コードを見つけることができます。



コンパクトなコードの例は、単一行のスクリプトです。 残念ながら、彼らはしばしばハックやあいまいな構文を使用します。 原則として、ネストされた三項演算子が使用されます。 コンパクトであるにもかかわらず、通常のif



とは異なり、何をしているのかを理解しようとして数秒を費やす必要があります。 そのため、構文の略語には注意してください。



適切なアプローチは、本番環境でコードを縮小することです。 ファイルの重量は軽く、ブラウザにより高速にロードされ、ページ全体のロード時間が短縮されます。 しかし、生産に便利な縮小ファイルは、開発において完全に不便です。 したがって、prodとvirgoで使用されるJSを分離し、各ファイルの2つのバージョン（縮小および完全）を保存し、構成で指定された環境に従って使用を切り替えることができます。

 // , -    ! var state = isHidden ? 'hidden' : isAnimating ? 'animating' : ''; // , -   ! var state = ''; if (isAnimating) state = 'animating'; if (isHidden) state = 'hidden';
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

パフォーマンスを改善するために設計されたマイクロ最適化は、多くの場合効果的ではありません。 そして、ほとんどの場合、生産性の低いものよりも読みにくくなります。

 //     $el[0].checked; //    ,    // : http://jsperf.com/prop-vs-ischecked/5 $el.prop('checked'); $el.is(':checked'); $el.attr('checked');
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

複数のポイントチェックの場合、スイッチを使用することをお勧めします。ポイント値のチェックが発生することは意味的に明確です。



JavaScriptコンパイラーはコードの最適化をうまく行っており、長年にわたってその最適化を行ってきました。 最適化されたコードと最適化されていないコードの違いが目立たない場合、数千または数百万の操作を使用するときにその部分が観察される場合、読みやすさを優先する方が良いです。

非コード

それを皮肉だと考えてください。しかし、コードを読みやすくする最善の方法は、実行不可能な構文を追加することです。 それを非コードと呼びましょう。 ただし、JSは一般的に、無視すべきではないコードフォーマット標準を受け入れていることを忘れないでください。 以下で説明します。

くぼみ

確かに、少なくとも一度はすべての開発者が自分の人生でコードを別の開発者に書き込むのを手伝ったり、すべてのスペースとインデントが削除された縮小コードを検査したりしました。 初めて、これはあなたにとって驚きだったに違いありません。 デザインやタイポグラフィなどのさまざまな視覚分野では、空き領域は塗りつぶしと同じくらい重要です。 ほとんどの場合、それらの間の微妙なバランスを見つけたいと思うでしょう。 このバランスに関する意見の範囲は、会社、チーム、および特定の開発者によって異なります。 幸いなことに、一般的に受け入れられているルールがいくつかあります。

• 1行に1つの式を使用します。
• インデントしてブロックを強調表示します。
• 追加のコードブレークを使用して、コードを分離できます。

他のルールは、一緒に働く人と話し合う必要があります。 ただし、設計するコードのスタイルに関係なく、重要なのは一貫性です。

 function sendPostRequest(url, data, cb) { //        var requestMethod = 'POST', requestHeaders = { 'Content-Type': 'text/plain' }; // ,    XMLHttpRequest var request = new XMLHttpRequest(); request.addEventListener('load', cb, false); request.open(requestMethod, url, false); request.send(data); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

コメント

インデントと同様に、コメントはコードを完全にまばらにすることができます。 同時に、コードの説明が含まれています。 必ずコメントを追加してください：

• 非自明なコードの説明と引数。
• この修正を使用して修正されたバグは、ソースを示しています。

 //     var sum = values.reduce(function(previousValue, currentValue) { return previousValue + currentValue; });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

すべての修正が明らかなわけではありません。 追加情報の導入により、多くのことが明らかになります。

 if ('addEventListener' in element) { element.addEventListener('click', myFunc); } // IE8     .addEventListener, //      .attachEvent // http://caniuse.com/#search=addEventListener // https://msdn.microsoft.com/en-us/library/ms536343%28VS.85%29.aspx else { element.attachEvent('click', myFunc); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

関数のドキュメントを使用するときは、コード内でコメントを使用せず、コメントを必要としない複数行の関数を作成することをお勧めします。 作業中は、 todoコメントを使用できます。多くのIDEはそれらの検索をサポートしています。 todoを使用すると、ファイナライズまたは完了する必要のあるコードピースがマークされます。 そのため、他の開発者は、計画と設計で定められたロジックであるアプローチを理解しやすくなります。 todoを適切な場所に置くことは非常に便利です。

統合ドキュメント

オブジェクト指向ソフトウェアを作成するとき、埋め込みドキュメントはコードをより自由にし、通常のコメントにすることができます。 また、プロパティとメソッドの機能の目的と詳細についても説明します。 多くのIDEは、ドキュメント生成ツールを使用するヒントとして組み込みのドキュメントを使用します！ 理由に関係なく、コードでドックを記述することは優れたソリューションです。

 /** *  HTTP- * @constructor * @param {string} url */ function HttpRequest(url) { // ... } /** *    * @param {Object} headers * @return {HttpRequest} */ HttpRequest.prototype.setHeaders = function(headers) { for (var header in headers) { this.headers[header] = headers[header]; } //    return this; };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

解説にはparam {Object}ヘッダーが示されていますが、このパラメーターに保存されて渡されるものの説明を提供する方が適切です。 この情報は、パラメーター自体の直後に示すことをお勧めします。 これがHolds success request headers（200）であるとしましょう。 次に、コメントは次のようになります。



@param {Object} headers Holds success request headers( 200 )







機能に関するドキュメントの形式はさまざまですが、チーム全体が同じ形式を使用することが非常に重要です。 開発者が1人の場合、異なる場所で同じ形式を使用する必要があります。 仮パラメータの説明では、仮パラメータのTIを示すことが必須です。 いくつかのIDEは、間違った型の変数が渡された場合、その場でプロンプトを表示します。 JSは動的な型指定を備えた言語であり、IDEがエラーをスローするという事実ではありませんが、そのようなドキュメントを解析するときに多くのエラーを回避できます。

コールバックのなぞなぞ

イベントと非同期呼び出しはJavaScriptの優れた機能ですが、多くの場合、コードの可読性を損ないます。

通常、非同期呼び出しにはコールバックが伴います。 時にはそれらを順番に実行する必要があり、時にはそれらすべての準備が整うまで待つほうが良い場合があります。 関数のドキュメントで、コールバック関数への参照を作成する必要があります。これにより、コールバック関数に簡単に移動したり、説明を確認したりできます。

 function doRequest(url, success, error) { /* ... */ } doRequest('https://example.com/api/users', function(users) { doRequest('https://example.com/api/posts', function(posts) { //  -     }, function(error) { //   /api/posts }); }, function(error) { //   /api/users });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

両方の問題を解決するために、PromiseオブジェクトがES2015（ES6とも呼ばれます）に実装されました。

 function doRequest(url) { return new Promise(function(resolve, reject) { //   //     resolve(response) //     reject(error) }); } //    doRequest('https://example.com/api/users') //     ,  .then() .then(function(users) { /* ... */ }) //    Promise   reject(),  .catch() .catch(function(error) { /* ... */ }); //    Promise Promise.all([ doRequest('https://example.com/api/users'), doRequest('https://example.com/api/posts') ]) .then(function(responses) { /* ... */ }) .catch(function(error) { /* ... */ });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

コードの一部を追加する必要がありましたが、通常は正しく解釈する方が簡単でした。 Promiseの詳細については、 JavaScript Goes Asynchronous（and It's Awesome）をご覧ください。

ES6 / ES2015

ES2015仕様を読んだ場合、この記事のすべてのコード例が古いバージョンのものであることにお気づきかもしれません（Promiseオブジェクトを除く）。 ES6には非常に幅広い可能性がありますが、ひどい読みやすさに関しては多くの不満があります。



太い矢印の構文は、親スコープからthis



を継承する関数を定義します。 少なくとも、このために作成されました。 また、通常の関数を定義するために使用するのも魅力的です。

 var add = (a, b) => a + b; console.log(add(1, 2)); // 3
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

別の例は、残りとスプレッドの構文です。

 /** *    * @param {Array} numbers * @return {Number} */ function add(...numbers) { return n.reduce(function(previousValue, currentValue) { return previousValue + currentValue; }, 0); } add(...[1, 2, 3]); /** *  a, b  c * @param {Number} a * @param {Number} b * @param {Number} c * @return {Number} */ function add(a, b, c) { return a + b + c; } add(1, 2, 3);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ES2015仕様では、非常に便利ですが、あいまいで、時には混乱を招く構文が批評家のターゲットになっています。 しかし、私たちはこれらの機会を放棄することについて話しているのではなく、単に注意してそれらを使用しています。

おわりに

コードの可読性と保守性を維持するには、プロジェクトのあらゆる側面を覚えておく必要があります。 ファイルシステムから小さな構文バリエーションまで、すべてが重要です。 これは、各参加者にすべてのルールを常に順守させることが難しいため、チームで作業する場合に特に顕著です。 問題の一部はコードの修正によって解決されますが、それでもエラーの可能性があります。 幸いなことに、いくつかの便利なツールがあります。

• JSHintは、コードのエラーを回避するJavaScriptリンターです。
• イディオマティックはコードをスタイリングするための一般的な標準ですが、逐語的に従う必要はありません。
• EditorConfig-クロスエディターコードスタイルの定義。

コードの複雑さを分析することは非常に重要であり、分析にはさまざまなアプローチがあります。 詳細については、 http ： //jscomplexity.org/complexityをご覧ください。



品質とスタイルを維持するためのツールに加えて、読みやすさを改善するためのツールがいくつかあります。 さまざまな構文強調スキームを試すか、ミニマップを使用してスクリプトを階層的に評価します（ Atom 、 Brackets ）。 たとえば、 https：//github.com/airbnb/javascriptは、かなり一般的なJSコードのフォーマット標準です。 コードのフォーマットと標準は使用するツールに依存することに注意してください。 たとえば、ReactとJSXの場合、他のスタイル要件があります。