refactor: console.log(式); //=> 評価結果 に表記を統一

CONTRIBUTING.md

@@ -83,8 +83,12 @@ or
 console.log(評価したい式); // => 期待する評価結果
 ```
 
+基本的には、`console.log(式); // => 期待する評価結果`を利用し、
+`console.log`が冗長な場合は `式; // => 期待する評価結果`と書いても良い。
+
 **関連**
 
+- [console.logと// => の使い分け · Issue #195 · asciidwango/js-primer](https://github.com/asciidwango/js-primer/issues/195 "console.logと// => の使い分け · Issue #195 · asciidwango/js-primer")
 - [power-assertを使ったDoctestツール power-doctestを書き直した | Web Scratch](http://efcl.info/2015/08/10/power-doctest1.0/)
 - [JavaScriptでdoctestを行う power-doctest を作った | Web Scratch](http://efcl.info/2013/1201/res3494/)
 - [25.2. doctest — 対話的な実行例をテストする — Python 2.7.x ドキュメント](http://docs.python.jp/2/library/doctest.html "25.2. doctest — 対話的な実行例をテストする — Python 2.7.x ドキュメント")

package.json

@@ -36,6 +36,8 @@
     "babel-preset-power-assert": "^1.0.0",
     "babel-register": "^6.7.2",
     "eslint": "^3.0.0",
+    "esprima": "^3.1.3",
+    "esquery": "^1.0.0",
     "front-matter": "^2.1.0",
     "gitbook-cli": "^2.1.2",
     "gitbook-plugin-canonical-link": "^2.0.2",

source/basic/data-type/README.md

@@ -127,7 +127,7 @@ JavaScriptの浮動小数点数は[IEEE 754][]を採用しています。
 - `3.14159` のような `.`（ドット）を含んだ数値
 - `2e8` のような `e` または `E` を含んだ数値
 
-`0`から始まる浮動小数点数は、`0`を省略し書くことができます。
+`0`から始まる浮動小数点数は、`0`を省略して書くことができます。
 
 ```js
 .123; // => 0.123
@@ -245,7 +245,7 @@ foo;// "ReferenceError: foo is not defined"
 {{book.console}}
 ```js
 var foo = null;
-foo; // => null
+console.log(foo); // => null
 ```
 
 ### オブジェクトリテラル {#object}
@@ -343,7 +343,7 @@ console.log(array[array.length - 1]); // => "2番目"
 ```js
 var numberRegExp = /\d+/; // 1文字以上の数字にマッチする正規表現
 // 123が正規表現にマッチするかをテストする
-numberRegExp.test(123); // => true
+console.log(numberRegExp.test(123)); // => true
 ```
 
 文字列から正規表現オブジェクトを作成することもできますが、

source/basic/function-method/README.md

@@ -58,7 +58,7 @@ function multiple(num) {
     return num * 2;
 }
 
-multiple(10); // => 20
+console.log(multiple(10)); // => 20
 ```
 
 値を返していない又は空の`return;`と書いた場合、関数は`undefined`を返します。
@@ -68,7 +68,7 @@ multiple(10); // => 20
 function noop() {
 }
 
-noop(); // => undefined;
+console.log(noop()); // => undefined;
 ```
 
 ### 可変長引数

source/basic/implicit-coercion/README.md

@@ -116,8 +116,8 @@ JavaScriptには、文字列に対するマイナス演算子（`-`）の定義
 {{book.console}}
 ```js
 var x = 1, y = "2", z = 3;
-x + y + z; // => "123"
-y + x + z; // => "213"
+console.log(x + y + z); // => "123"
+console.log(y + x + z); // => "213"
 ```
 
 このように、処理の過程でオペランドの型によって、

source/basic/operator/README.md

@@ -145,11 +145,11 @@ Math.pow(2, 4); // => 16
 {{book.console}}
 ```js
 // 自分自身とも一致しない
-NaN === NaN; // => false
+console.log(NaN === NaN); // => false
 // Number型である
-typeof NaN; // => "number"
+console.log(typeof NaN); // => "number"
 // Number.isNaNでNaNかどうかを判定
-Number.isNaN(NaN); // => true
+console.log(Number.isNaN(NaN)); // => true
 ```
 
 しかし、単項演算子の`+`は文字列から数値への変換に使うべきではありません。

source/basic/string/README.md

@@ -112,14 +112,14 @@ ES2015で追加された`String#codePointAt`メソッドを使うことで、そ
 
 ```js
 // 文字列"あ"の0番目のCode Pointを取得
-"あ".codePointAt(0); // => 12354
+console.log("あ".codePointAt(0)); // => 12354
 ```
 
 逆に、`String.fromCodePoint`メソッドを使うことで、指定したCode Pointの文字を取得できます。
 
 ```js
 // 符号位置12354の文字を取得する
-String.fromCodePoint(12354); // => "あ"
+console.log(String.fromCodePoint(12354)); // => "あ"
 ```
 
 また、文字列リテラル中にはUnicodeエスケープシーケンスで、直接Code Pointを書くこともできます。
@@ -128,7 +128,7 @@ Code Pointは`\u{Code Pointの16進数の値}`で書くことができます。
 ```js
 // "あ"のCode Pointは12354
 // 12354の16進数表現は3042
-"\u{3042}"; // => "あ"
+console.log("\u{3042}"); // => "あ"
 ```
 
 Code Pointの16進数表現は次のようにして求めることができます。
@@ -139,7 +139,7 @@ var codePointOfあ = "あ".codePointAt(0);
 // 12354の16進数表現は"3042"
 var hexOfCodePoint = codePointOfあ.toString(16);
 // \はエスケープシーケンスであるため、\自体を表現するにはエスケープが必要
-"\\u{" + hexOfCodePoint + "}"; // => "\\u{3042}"
+console.log("\\u{" + hexOfCodePoint + "}"); // => "\\u{3042}"
 ```
 
 直接キーボードから入力が難しい特殊な文字や絵文字などは、Unicodeエスケープシーケンスを使うことでソースコード上に安全に書くことができます。
@@ -423,7 +423,8 @@ JavaScriptでは、ECMAScriptの関連仕様として国際化API（ECMAScript I
 // numericをtrueとすると数字が数値として比較されるようになる
 var collator = new Intl.Collator("ja", { numeric: true });
 // collator.compareはsortに渡せる関数となっている
-["1", "10", "2"].sort(collator.compare); // => ["1", "2", "10"]
+var sortedValues = ["1", "10", "2"].sort(collator.compare);
+console.log(sortedValues);  // => ["1", "2", "10"]
 ```
 
 文字列の比較においては、単純な比較であれば、`===`（厳密比較演算子）や`>`（大なり演算子）を利用します。

test/lib/console-comment.js

@@ -0,0 +1,87 @@
+// MIT © 2017 azu
+"use strict";
+const esprima = require("esprima");
+const esquery = require("esquery");
+const path = require("path");
+const ignoreFileList = [
+    // 演算子はいいかな
+    "source/basic/operator",
+    // これもリテラルの話なので…
+    "source/basic/implicit-coercion"
+];
+/**
+ * 変数を含んでいるか
+ * @param {Object} AST
+ * @returns {boolean}
+ */
+const isIncludeVariableInExpression = (AST) => {
+    // 例外
+    // call({ x : 1})
+    const Identifiers = esquery(AST, "*:not(Property) Identifier");
+    if (Identifiers.length > 0) {
+        return true;
+    }
+    return false;
+};
+/**
+ * コードで `評価式; // => 評価値` を利用している箇所で
+ * `console.log`を付けるかどうかを判定する
+ * https://github.com/asciidwango/js-primer/issues/195
+ *
+ * - 基本的にはconsole.logを利用する
+ * - リテラルや変数が登場しないコードでは`console.log`を省いても良い
+ *
+ * lineが問題ある行ならばErrorオブジェクトを返す
+ * @param {string} text
+ * @param {string} filePath ファイルパスは無視したい対象の指定に使う
+ * @returns {Error|undefined}
+ */
+module.exports = function shouldConsoleWithComment(text, filePath) {
+    const lines = text.split("\n");
+    // 1行以下なら無視する
+    if (lines.length <= 1) {
+        return;
+    }
+    lines.forEach(line => {
+        const error = checkLineThatShouldHaveComment(line, filePath);
+        if (error instanceof Error) {
+            throw error;
+        }
+    });
+};
+/**
+ * @param {string} line
+ * @param {string} filePath
+ * @returns {Error|undefined}
+ */
+function checkLineThatShouldHaveComment(line, filePath) {
+    if (!/\/\/\s*=>\s*/.test(text)) {
+        return;
+    }
+    if (text.includes("console.")) {
+        return;
+    }
+    // エラーの場合は無視
+    if (/=>.*Error/.test(text)) {
+        return;
+    }
+    // template literalっぽいのは無視
+    if (text.includes("`")) {
+        return;
+    }
+
+    const AST = esprima.parse(text);
+    // 変数を含まないリテラルのみであるならパスする
+    if (!isIncludeVariableInExpression(AST)) {
+        return;
+    }
+    // 無視リストに含まれているなら無視
+    const isIgnored = ignoreFileList.some(ignoreFilePath => {
+        return filePath.includes(path.normalize(ignoreFilePath));
+    });
+    if (isIgnored) {
+        return;
+    }
+    return new Error(`console.log(式); // => 評価結果 にそろえてください
+該当コード: ${text}`);
+}

test/markdown-doc-test.js

@@ -9,6 +9,7 @@ const sourceDir = path.join(__dirname, "..", "source");
 const toDoc = require("power-doctest");
 const remark = require("remark")();
 const select = require('unist-util-select');
+const shouldConsoleWithComment = require('./lib/console-comment');
 
 /**
  * 指定した文字列を含んだコードは実行環境によってはサポートされてないので無視する
@@ -21,7 +22,11 @@ const ESVersions = ["ES2016", "ES2017"];
  * CodeBlockは必ず実行できるとは限らないので、
  * AssertionError(doctestにおける失敗)以外は成功したことにして無視する
  * Node.js v6はES2016-が実行できないのでスルーする
- * 詳細は CONTRIBUTING.md を読む
+ *
+ * `console.log(式); // => 結果` の書式で書かれているをチェックする
+ * https://github.com/asciidwango/js-primer/issues/195
+ *
+ * その他詳細は CONTRIBUTING.md を読む
  **/
 describe("doctest:md", function() {
     const files = globby.sync([`${sourceDir}/**/*.md`, `!${sourceDir}/**/node_modules{,/**}`]);
@@ -38,6 +43,8 @@ describe("doctest:md", function() {
                     return codeValue.includes(version);
                 });
                 try {
+                    // console.logと// => の書式をチェック
+                    shouldConsoleWithComment(codeBlock.value, filePath);
                     const poweredCode = toDoc.convertCode(codeBlock.value, filePath);
                     strictEval(poweredCode);
                 } catch (error) {