review - comments

Author: KenjiI

1-js/03-code-quality/03-comments/article.md

@@ -4,7 +4,7 @@
 
 通常はそれを使用して、どうやって/なぜそのコードが動作するのかを説明します。
 
-一見するとコメントすることは当たり前かもしれませんが、プログラム初心者は通常間違った思い込みをします。
+一見、コメントすることは当たり前かもしれませんが、プログラム初心者は間違った思い込みをすることがあります。
 
 ## 悪いコメント 
 
@@ -18,13 +18,13 @@ complex;
 code;
 ```
 
-しかし良いコードでは、このような "説明的な" コメントは最小限にすべきです。真面目にコードはそれらなしで理解しやすくするべきです。
+しかし良いコードでは、このような "説明的な" コメントは最小限にすべきです。真面目にそれらがなくても理解しやすいコードにするべきです。
 
 それに関して素晴らしいルールがあります。"もしもコードがコメントを必要とするほど不明瞭な場合、書き直すべきかもしれません"。
 
-### レシピ: 関数を取り除く
+### レシピ: 機能を括り出す
 
-時々、このようにコードの一部を関数に置き換えることは有益です:
+このように、コードの一部を関数に置き換えることは有益な場合があります:
 
 ```js
 function showPrimes(n) {
@@ -65,11 +65,11 @@ function isPrime(n) {
 }
 ```
 
-今や、私たちは簡単にコードを理解することが出来ます。関数自身がコメントになります。このようなコードは *自己記述的* と呼ばれます。
+今や、私たちは簡単にコードを理解することができます。関数自身がコメントになります。このようなコードは *自己記述的* と呼ばれます。
 
 ### レシピ: 関数を作成する
 
-また、もしこのような長い "コードシート" を持っている場合:
+また、もしこのような長い "コードの塊" がある場合:
 
 ```js
 // here we add whiskey
@@ -90,7 +90,7 @@ for(let t = 0; t < 3; t++) {
 // ...
 ```
 
-次のような関数にリファクタリングするのがより良い方法かもしれません:
+次のように関数にリファクタリングするのがより良い方法かもしれません:
 
 ```js
 addWhiskey(glass);
@@ -111,13 +111,13 @@ function addJuice(container) {
 }
 ```
 
-改めて言いますが、関数自身が何が行われているのかを伝え、コメントすることは何もありません。また分割するとコードの構造はより良くなります。各関数がすること、何を取り何を返すのかは明白です。
+改めて言いますが、関数自身が何が行われているのかを伝えているので、コメントすることは何もありません。また分割するとコードの構造はより良くなります。各関数がすること、何を引数として取り、何を返すのかは明白です。
 
-現実では、完全に "説明的な" コメントを避けることはできません。複雑なアルゴリズムがあります。そして最適化のためのスマートな "微調整" があります。しかし、一般的にはコードをシンプルで自己記述的に保つよう努めるべきです。
+現実では、完全に "説明的な" コメントを避けることはできません。複雑なアルゴリズムがあり、その最適化のための賢明な "微調整" がコードの中で行われることがあります。しかし、一般的にはコードをシンプルで自己記述的に保つよう努めるべきです。
 
 ## 良いコメント 
 
-これまでの通り、説明的なコメントは通常良くありません。ではどんなコメントが良いでしょう？
+これまでの通り、説明的なコメントは通常良くありません。ではどんなコメントが良いのでしょう？
 
 アーキテクチャの説明をする
 : 高水準のコンポーネントの概要、相互作用の方法、様々な状況での制御フローを説明します... つまり -- コードの俯瞰図です。それは高水準のアーキテクチャ図のための特別な言語[UML](http://wikipedia.org/wiki/Unified_Modeling_Language)があります。これは間違いなく学ぶ価値があります。
@@ -141,30 +141,30 @@ function addJuice(container) {
 
     このようなコメントにより、関数の目的を理解し、コードの中を見ることなく正しい方法で利用することができます。
 
-    ところで、[WebStorm](https://www.jetbrains.com/webstorm/) のような多くのエディタも同様にそれらを解釈することができ、オートコンプリートやいくつかの自動コードチェックを提供するのに使います。
+    ちなみに、[WebStorm](https://www.jetbrains.com/webstorm/) のような多くのエディタも同様にそれらを解釈することができ、それらを使ってオートコンプリートや自動コードチェックを提供します。
 
     また、コメントからHTMLドキュメントを生成することができる [JSDoc 3](https://github.com/jsdoc3/jsdoc) のようなツールもあります。JSDocに関するより多くの情報は <http://usejsdoc.org/> で読むことができます。
 
-なぜこのように解決されるのか？
-: 何が書かれているかは重要です。が、起こっていることを理解するためには、*書かれていないこと* がより重要かもしれません。正確にはなぜそのタスクがこの方法で解決されるのか？コードは回答しません。
+タスクがこのように解決されるのはなぜか？
+: 書かれていることは重要です。が、何が起こっていることを理解するためには、*書かれていないこと* がより重要かもしれません。なぜそのタスクがこの方法で正しく解決されるのか？コードは回答しません。
 
-    もしそのタスクを解決る方法が沢山有る場合、なぜこれを選んだのでしょう？特に、それが最も明白なものではないとき。
+    もしそのタスクを解決する方法が多数ある場合、なぜこれを選んだのでしょう？特に、それが最も明白なものではないとき。
 
     このようなコメントがなければ、次のような状況が起こりえます:
     1. あなた(もしくは同僚) はいくらか前に書かれたコードを開き、それが "準最適" であることを確認します。
-    2. あなたは考えます: "私はなんて愚かだったのか、そして今はどれだけスマートになったのか"、そして "より明白で正しい" 方法を使って書き直します。
-    3. ... 書き直すと言う衝動は良かったです。しかし、そのプロセスではあなたは "より明白な" 解決策は実際には不十分であることに気付きます。既にずっと前にそれを試みており、なぜダメなのかをぼんやり覚えています。あなたは最終的に正しい方法に戻しますが、時間が無駄になりました。
+    2. あなたは考えます: "私はなんて愚かだったのか、そして今はどれだけ賢くなったのか"、そして "より明白で正しい" 方法を使って書き直します。
+    3. ... 書き直したいという思いは良かったです。しかし、そのプロセスの中であなたは "より明白な" 解決策は実際には不十分であることに気付きます。実は既に以前試みたことであり、なぜダメだったのかぼんやり覚えています。最終的に元の正しい方法に戻します。が、その分時間が無駄になりました。
 
-    解決策を説明するコメントはとても重要です。それらは正しい方向で開発を続けるのを助けます。
+    解決策を説明するコメントはとても重要です。それらは正しい方向で開発を続けるのに役立ちます。
 
 コードの捉えにくい特徴はある？それらはどこで使われる？
-: もしもコードが捉えにくく、紛らわしいものがある場合には、きっとコメントする価値があります。
+: もしもコードが捉えにくく、紛らわしいものがある場合にはきっとコメントする価値があります。
 
 ## サマリ 
 
-よい開発者の重要なサインはコメントです: それらの存在、またそれらの欠如。
+よい開発者の重要なサインはコメントです: それらの存在、またそれらの欠如によって。
 
-よいコメントはコードを上手く維持し、時間が経った後にそこに戻り、より有効に使用できるようにします。
+よいコメントはコードを上手く維持し、時間が経った後でそこに戻ったときにも効果的に使えるようにします。
 
 **コメントすること:**
 
@@ -177,4 +177,4 @@ function addJuice(container) {
 - "どのようにコードが動くか" そして "それが何をするか" を伝える
 - コードを、コメントを必要としないような、シンプルで自己記述的にすることが不可能な場合にのみ置きます。
 
-コメントはJSDoc3のような自動文書化ツールにも使われます: それらはコメントを読んで、HTML-docs（または別の形式の文書）を生成します。
+コメントはJSDoc3のような自動文書化ツールにも使われます: それらはコメントを解釈し、HTML-docs（または別の形式の文書）を生成します。