2015-12-22: リーダブルコードメモ

[kou]

「自分が書いたリーダブルコード」と「自分が見つけたリーダブルコード」をここにメモしていっていてください。目的は「リーダブルコードを見つける練習」です。単に「書く」「見つける」だけでなく、「メモとしてまとめる」ことまですることで「再利用可能な状態」（＝他の人に説明できる、他の場面で同じ書き方を適用できる）まで自分の中で整理されることを期待しています。

1つのリーダブルコードにつき1つのコメントにしてください。

各コメントには次の内容を含めてください。

• サマリー（あるいはタイトルあるいは一言説明）
• 実際のコード
• どうしてリーダブルだと考えたかの説明
• 「見つけた」場合のみ：見つけた経緯（あるいはきっかけ）

コメントに書くときは次のテンプレートを使ってください。

### サマリー

（ここにサマリーを書く）

### 実際のコード

```java
（ここに実際のコードを書く）
```

### どうしてリーダブルだと考えたかの説明

（ここに説明を書く）

### 見つけた経緯

（「見つけた」場合のみ。ここに見つけた経緯を書く。）

以下は具体例です。

---

サマリー

自己記述的定数名

実際のコード

https://github.com/doraemon13x/doraemon13x-sezemi-2014-readable-code-2/blob/master/mission3.c#L9

exit(EXIT_FAILURE); /* エラーの場合は異常終了する */

どうしてリーダブルだと考えたかの説明

コマンドの終了ステータスは、正常終了するときは0、異常終了するときは0以外の値を返すのが通例です。そのため、このコードは次のようにしても通例通りの動きになります。

exit(1);

ただ、動くのは動きますが、EXIT_FAILUREという名前を使っている方が「失敗して終了するんだな」というのがわかりやすいのでリーダブルだと考えました。

なお、EXIT_SUCCESSというのもあるので、同様の理由で正常終了するときはそれを使うのがよいと思います。

見つけた経緯

ちゃんとエラー処理をしていて立派だなぁと思って読み進めたら異常終了することがわかりやすいコードだと気づきました。

---

[yoshidki]

サマリー

プロジェクト作成

実際のコード

なし

どうしてリーダブルだと考えたかの説明

プロジェクトの作成と実際の作業のコミットを分離して、あとから読みやすくなった。

見つけた経緯

なし

[jswaf]

サマリー

変数名とクラス名でコメントなくてもリーダブル

実際のコード

/**
 * 2015/12/22 リーダブルコードワークショップ課題
 *
 * @author Wataru Fuksuhima
 */
public class TaskExample {
    /**
     * エントリポイント。
     */
    public static void main(String[] arguments) {
        doSpec1();
    }

    /**
     * 仕様1：レシピ情報を出力できること
     *
     * レシピのタイトルとして「オムライス」と出力するプログラムを新しく作ってください。
     *
     * レシピのタイトルの出力先は問いません。コンソールに出力しても構いませんし、
     * ファイルに出力しても、ウィンドウを作ってそこに出力しても、Webブラウザーに
     * 表示させても構いません。
     *
     * 入力
     *
     * なし
     *
     * 期待する結果
     *
     * プログラムが実行されたら、なんらかの形で「オムライス」と出力すること。
     */
    private static void doSpec1() {
        Recipe omeletRiceRecipe = new OmeletRiceRecipe();
        System.out.println(omeletRiceRecipe.getTitle());
    }
}

/**
 * レシピのインタフェース。
 *
 * @author Wataru Fuksuhima
 */
public interface Recipe {
    /**
     * タイトルを取得します。
     *
     * @return タイトル
     */
    String getTitle();
}

/**
 * オムライスのレシピ
 *
 * @author Wataru Fuksuhima
 */
public class OmeletRiceRecipe implements Recipe {
    /** タイトル */
    private static final String TITLE = "オムライス";

    /**
     * コンストラクタ。
     */
    public OmeletRiceRecipe() {
    }

    /**
     * タイトルを取得します。
     *
     * @return タイトル
     */
    @Override
    public String getTitle() {
        return TITLE;
    }
}

どうしてリーダブルだと考えたかの説明

• 実行コードにコメントがなくても名前だけで何をやっているかが分かる。
• クラスを役割毎に分けて分割統治しやすくした。

見つけた経緯

自分で書いたため省略

[kalbee98]

サマリー

ソースコード格納用フォルダを作成した

実際のコード

なし

どうしてリーダブルだと考えたかの説明

README.txt　にプロジェクト構成を記述することで、理解しやすくなる。

見つけた経緯

（「見つけた」場合のみ。ここに見つけた経緯を書く。）

[yoshioky]

サマリー

自己記述的定数名

実際のコード

_tprintf(recipeTitle.c_str());

どうしてリーダブルだと考えたかの説明

レシピタイトルの出力であることが変数名からわかる

[fumihisa-suzuki]

サマリー

分かり易いクラス名

実際のコード

public class RecipeWriter {
...

どうしてリーダブルだと考えたかの説明

何をするクラスかすぐにわかるクラス名だから

見つけた経緯

[yoshioky]

サマリー

ひとまとまりの処理を関数化

実際のコード

void suspendCommandLine()
{
    char dummy[256];
    gets_s(dummy);
}
int _tmain(int argc, _TCHAR* argv[])
{
    // 処理

    suspendCommandLine();
    return 0;
}

どうしてリーダブルだと考えたかの説明

べた書きするとどういう意図で入れた処理かわからないが、関数化して命名したことで意味がわかりやすくなった。

[suzukke-js]

サマリー

わかりやすいクラス名、メソッド名

実際のコード

class Recipe
{
public:
    Recipe(LPCWSTR title_);
    std::wstring GetTitle();
private:
    std::wstring title;
};

int _tmain(int argc, _TCHAR* argv[])
{
    ...
    Recipe recipe(L"オムライス");
    std::wcout << recipe.GetTitle();
    ...
}

どうしてリーダブルだと考えたかの説明

「レシピのタイトルを出力する」という意図が、コードから読み取れる。

見つけた経緯

[suzukke-js]

サマリー

おまじないコードへのコメント記述

実際のコード

int _tmain(int argc, _TCHAR* argv[])
{
    // 日本語出力用のロケール設定
    setlocale(LC_ALL, "ja-JP");
    ...
}

どうしてリーダブルだと考えたかの説明

「おまじない」のコードは意図が分かりにくくなる傾向あり。
コメントにより意図が伝わりやすくなる。

見つけた経緯

[yoshidki]

サマリー

出力する機能の分離

実際のコード

/**
 * 与えられた文字列を出力するインターフェイス
 * 
 * @author yoshidki
 *
 */
public interface OutputService {
    /**
     * 引数で与えられた文字列を出力する
     * 
     * @param str
     */
    public void output(String str);
}

どうしてリーダブルだと考えたかの説明

出力する処理をインターフェイスで分離することで、出力先の変更が簡単にできるようになります。

見つけた経緯

[t-sugai]

サマリー

開発環境の標準的な流儀に乗る

実際のコード

（なし）

.project ファイルの存在、プロジェクトファイル構成全般

どうしてリーダブルだと考えたかの説明

Eclipseを使っていればフォルダごとインポートしてくればそのまま開発を引き継げる
独自の変更や拡張などを無理にしていないため、Eclipseでの開発の経験さえあればすぐにキャッチアップできるはず

[mukkuworld]

サマリー

クラスメンバー変数であることを明示する

実際のコード

this->m_staticText.SetWindowText( _T("オムライス") );

どうしてリーダブルだと考えたかの説明

「this->」と記述することで、その隣の変数がクラスのメンバー変数であることが分かる。

見つけた経緯

変数m_staticTextがどこまで影響するのか一目でわかった。

[fumihisa-suzuki]

サマリー

変数のスコープをの所化

実際のコード

for (String line; (line = reader.readLine()) != null;) {
    writer.write(line);
}

どうしてリーダブルだと考えたかの説明

変数がループ内でしか使用されないことがはっきりとわかる。

見つけた経緯

[mukkuworld]

サマリー

実装方針をコメントで記載しておく。

実際のコード

    // 実装途中です。すみません
    // ファイルから読み込む部分を作成してください

どうしてリーダブルだと考えたかの説明

どこへ実装を追加すれば実現できるかが分かる

見つけた経緯

須藤さんからの指摘

[yoshioky]

サマリー

周辺情報を説明

実際のコード

Readme.txtより

レシピ情報出力プログラム

■ビルド手順
1. Visual Studio 2013で Recipe.sln を開く。
2. ビルドを実行する。

■実行手順
1. コマンドプロンプトを起動する。
2. ビルド構成に応じて、DebugもしくはReleaseフォルダーをカレントにする。
3. そのフォルダーに、レシピデータを記述したテキストファイルを作成する。
　ファイル名：任意
　中身　　　：１行目にレシピ情報を指定する
4. コマンドプロンプトから「Recipe.exe レシピファイル名」を実行する
　例）Recipe.exe recipe-data.txt

どうしてリーダブルだと考えたかの説明

手順が詳細に書いてあるので、説明を受けなくても実行・デバッグができる

見つけた経緯

Readme.txtを開いてみた