初心者を卒業！現役が教えるプログラミング上達方法

のえる

2019.09.04

みなさん、プログラム書いてますか？

今回は今までの経験から、プログラム初心者の方の上達のコツを書いていこうと思います。

ただ上達には色々な意味があると思いますが、
この記事ではコピペを卒業し、自分で”見やすい”プログラムを書いていけるようになるとします。

また、既にプログラムをがっつり書いている方も軽く目を通してもらうと、参考になることが書いてあるかもしれません。

1 はじめに
2 環境編
3 さいごに

はじめに

まずはじめに見やすいプログラムに100%の正解は存在しないということを述べておきます。

これは複数の要因がありますが、プログラム言語や開発環境、果ては状況によって変わってしまうものだからです。

「うちの会社ではこう書いてる」と言っても、他社では「こっちの書き方をしているから直してくれ」と言われるくらいです。

ですので、初心者の方は共感・納得できるものから取り入れてみるくらいの感覚で少しずつ取り入れていってみてください。

一気に上達は難しいと思いますが、確実に一歩ずつ上達に近づいていくと思います。

例題はPHPという言語で書かれていますが、本質はどの言語でも基本的に同じです。

環境編

タブとスペース(半角/全角)を混在しない

開発をしているとき、みなさんはタブ、スペースのどちらを使っていますか？
どちらを使っても間違いではありませんが混在させることは避けた方がいいです。

これの理由は可読性(読みやすさ)が落ちる可能性があるからです。
これはタブの表示が一定とは限らないためです。
下記に具体例を見てみましょう。

タブ1つで半角スペース4つと設定されているエディタの場合


<!--?php 
    $flg = 1;

    $apple = "りんご";
    $orange = "みかん";

    if($flg == 1) {
        echo $apple;
    } else {
        echo $orange;
    }
</pre>
<p>インデント（字下げ）が整っていて非常に見やすいですね。<br ?-->
混在して書いた人にはこのように見えています。

<!--?php

$flg = 1;

$apple = "りんご";

$orange = "みかん";

if($flg == 1) {

echo $apple;

} else {

echo $orange;

}

</pre>

インデント（字下げ）が整っていて非常に見やすいですね。

混在して書いた人にはこのように見えています。

では別のエディタで開いてみましょう。

タブ1つで半角スペース2つと設定されているエディタの場合


<!--?php 
    $flg = 1;

  $apple = "りんご";
    $orange = "みかん";

    if($flg == 1) {
    echo $apple;
  } else {
        echo $orange;
    }
</pre>
<p>&nbsp;</p>
<p>同じプログラムなのにインデントがぐちゃぐちゃで読みづらいですね。</p>
<p>&nbsp;</p>
<p>様々なサイトからコピー＆ペーストをした初心者にありがちなソースコードで、他の人が読むことを意識していない場合に発生します。</p>
<p>&nbsp;</p>
<p>開発は多人数で行うことも多いので、[marker color="green"]他の人が読むことを常に意識[/marker]しましょう。</p>
<h3>文字コードを統一する</h3>
<p>プログラムを書いていくとき、複数のファイルに分割していくことがあります。<br ?-->
この時、それぞれのファイルで文字コードが違うと、思わぬ問題が発生することがあります。

<!--?php

$flg = 1;

$apple = "りんご";

$orange = "みかん";

if($flg == 1) {

echo $apple;

} else {

echo $orange;

}

</pre>

同じプログラムなのにインデントがぐちゃぐちゃで読みづらいですね。

様々なサイトからコピー＆ペーストをした初心者にありがちなソースコードで、他の人が読むことを意識していない場合に発生します。

開発は多人数で行うことも多いので、[marker color="green"]他の人が読むことを常に意識[/marker]しましょう。

<h3>文字コードを統一する</h3>

プログラムを書いていくとき、複数のファイルに分割していくことがあります。

この時、それぞれのファイルで文字コードが違うと、思わぬ問題が発生することがあります。

ファイルBのプログラムで、ファイルAの中身を読み込んで使用する時、それぞれの文字コードが異なると読み込んだデータが破損した扱いになってしまう事があります。

データが破損する＝読み取れないとなってしまいますがプログラム自体には問題がないため、問題解決時に不要な時間がかかってしまいます。

プロでもこの手の問題解決には時間がかかるため、初心者のうちから文字コードを統一するクセをつけましょう。

エディタのカラーテーマを設定する

メモ帳などの白背景＋黒文字でももちろん動きますが、プログラムのミスにつながります。
具体的には入力ミスに気付きにくくなるという問題があります。


<!--?php // ミスが無いプログラム $array = array( "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);

    // ミスしているプログラム
    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);
</pre>
<p>&nbsp;</p>
<p>変数はオレンジ、定数はピンク、関数は青 etc.</p>
<p>&nbsp;</p>
<p>それぞれで分かりやすい色に設定したりすると[marker color="green"]ミスにすぐ気づけます[/marker]。<br ?-->
また、タブや全角スペースなども色付けしておくと、スペースとタブの混在にも気づけます。

<!--?php // ミスが無いプログラム $array = array( "foo" => "bar",

42 => 24,

"multi" => array(

"dimensional" => array(

"array" => "foo"

)

);

var_dump($array["foo"]);

var_dump($array[42]);

var_dump($array["multi"]["dimensional"]["array"]);

// ミスしているプログラム

$array = array(

"foo" => "bar",

42 => 24,

"multi => array(

"dimensional" => array(

"array" => "foo"

)

);

var_dump($array["foo"]);

var_dump($array[42]);

var_dump($array["multi"]["dimensional"]["array"]);

</pre>

変数はオレンジ、定数はピンク、関数は青 etc.

それぞれで分かりやすい色に設定したりすると[marker color="green"]ミスにすぐ気づけます[/marker]。

また、タブや全角スペースなども色付けしておくと、スペースとタブの混在にも気づけます。


<!--?php // ミスが無いプログラム $array = array( "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);

    // ミスしているプログラム
    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);
</pre>
<p>上記の例では、囲い文字(ダブルクオーテーション)が付け忘れていることがすぐにわかります。</p>
<h2>書き方編</h2>
<h3>固定の値を直接書かない</h3>
<p>プログラムに直接固定の値を書くと [marker weight="narrow" color="green"]後で見た人が何の値かわからない[/marker] 、 [marker weight="narrow" color="blue"]他で使う場合もある時、値を変更しようとするとプログラムを全部見直すことになる[/marker] などの問題が発生します。<br ?-->
具体的にプログラムを見てみましょう。

<!--?php // ミスが無いプログラム $array = array( "foo" => "bar",

42 => 24,

"multi" => array(

"dimensional" => array(

"array" => "foo"

)

);

var_dump($array["foo"]);

var_dump($array[42]);

var_dump($array["multi"]["dimensional"]["array"]);

// ミスしているプログラム

$array = array(

"foo" => "bar",

42 => 24,

"multi => array(

"dimensional" => array(

"array" => "foo"

)

);

var_dump($array["foo"]);

var_dump($array[42]);

var_dump($array["multi"]["dimensional"]["array"]);

</pre>

上記の例では、囲い文字(ダブルクオーテーション)が付け忘れていることがすぐにわかります。

<h3>固定の値を直接書かない</h3>

プログラムに直接固定の値を書くと [marker weight="narrow" color="green"]後で見た人が何の値かわからない[/marker] 、 [marker weight="narrow" color="blue"]他で使う場合もある時、値を変更しようとするとプログラムを全部見直すことになる[/marker] などの問題が発生します。

具体的にプログラムを見てみましょう。


<!--?php 
    $shincho = 170;

    if(120 <= $shincho) {
        echo "乗車可能です";
    } else {
        echo "身長120cm未満の人はご乗車いただけません。";
    }
</pre>
<p>上記プログラムでは身長が120cm未満の場合、ジェットコースターには乗れないという判定になっています。</p>
<p>&nbsp;</p>
<p>ではもし [marker weight="narrow" color="yellow"]身長を130㎝未満に変更してほしい[/marker] という話が出たら、何か所直すことになるでしょうか？<br ?-->
このプログラムでは2か所直すことになりますが、もっと複雑なプログラムで他のファイルにまで使用されていたら、目も当てられません。

<!--?php

$shincho = 170;

if(120 <= $shincho) {

echo "乗車可能です";

} else {

echo "身長120cm未満の人はご乗車いただけません。";

}

</pre>

上記プログラムでは身長が120cm未満の場合、ジェットコースターには乗れないという判定になっています。

ではもし [marker weight="narrow" color="yellow"]身長を130㎝未満に変更してほしい[/marker] という話が出たら、何か所直すことになるでしょうか？

このプログラムでは2か所直すことになりますが、もっと複雑なプログラムで他のファイルにまで使用されていたら、目も当てられません。

ですので、下記のように定数化や変数化しておくことが望ましいです。


<!--?php 
    const LIMIT_SHINCHO = 120;

    $shincho = 170;

    if(LIMIT_SHINCHO <= $shincho) {
        echo "乗車可能です";
    } else {
        echo "身長".LIMIT_SHINCHO."cm未満の人はご乗車いただけません。";
    }
</pre>
<p>これなら定数の値を変更するだけですぐ終わりますね。<br ?-->
複数のファイルで使用する場合は、定数を集めたファイルを外部化しておき、各ファイルで読み込むのも手です。

<!--?php

const LIMIT_SHINCHO = 120;

$shincho = 170;

if(LIMIT_SHINCHO <= $shincho) {

echo "乗車可能です";

} else {

echo "身長".LIMIT_SHINCHO."cm未満の人はご乗車いただけません。";

}

</pre>

これなら定数の値を変更するだけですぐ終わりますね。

複数のファイルで使用する場合は、定数を集めたファイルを外部化しておき、各ファイルで読み込むのも手です。

書き方を統一する（コーディング規約を作る）

たとえば定数はすべて大文字や変数はキャメルケースなど、プログラムの書き方を一定に保っておくことでプログラムの読みやすさ（可読性）と管理・修正のしやすさ（保守性）が上がります。

キャメルケースは、複合語をひと綴りとして、要素語の最初を大文字で書き表すことをいう。
キャメルケース – Wikipedia –

悪い例


<!--?php 
    // 書き方が決まっていない定数
    const gp01 = "ゼフィランサス";
    const GP02 = "サイサリス";
    const Gp_03 = "デンドロビウム";
    const gP04 = "ガーベラ";

    // 書き方が決まっていない変数
    $cure_star = "マイアミピンク";
    $CureMilky = "青緑";
    $cureSoleil = "黄色";
    $CURESELENE = "紫";
    $curecosmo = "虹色・青";
</pre>
<p>書き方が統一されていないプログラムはどうですか？ 読みづらくないですか？<br ?-->
これは [marker color="yellow"]複数人がプログラムを修正した際、前の人の記述ルールに合わせず自分勝手なプログラムを書いたとき[/marker] によく起こります。

<!--?php

// 書き方が決まっていない定数

const gp01 = "ゼフィランサス";

const GP02 = "サイサリス";

const Gp_03 = "デンドロビウム";

const gP04 = "ガーベラ";

// 書き方が決まっていない変数

$cure_star = "マイアミピンク";

$CureMilky = "青緑";

$cureSoleil = "黄色";

$CURESELENE = "紫";

$curecosmo = "虹色・青";

</pre>

書き方が統一されていないプログラムはどうですか？読みづらくないですか？

これは [marker color="yellow"]複数人がプログラムを修正した際、前の人の記述ルールに合わせず自分勝手なプログラムを書いたとき[/marker] によく起こります。

では、きれいに直していきましょう。

良い例


<!--?php 
    // 書き方が決まっている定数 (「定数は全部大文字」というルール)
    const GP01 = "ゼフィランサス";
    const GP02 = "サイサリス";
    const GP03 = "デンドロビウム";
    const GP04 = "ガーベラ";

    // 書き方が決まっている変数 (「変数は全部ローワーキャメルケース」というルール)
    $cureStar = "マイアミピンク";
    $cureMilky = "青緑";
    $cureSoleil = "黄色";
    $cureSelene = "紫";
    $cureCosmo = "虹色・青";
</pre>
<p>プログラムが統一され綺麗になり、非常に読みやすくなりました。<br ?-->
これは他人が見ても [marker color="green"]そういうルールなのか[/marker] と気づきやすくなる効果もあります。

<!--?php

// 書き方が決まっている定数 (「定数は全部大文字」というルール)

const GP01 = "ゼフィランサス";

const GP02 = "サイサリス";

const GP03 = "デンドロビウム";

const GP04 = "ガーベラ";

// 書き方が決まっている変数 (「変数は全部ローワーキャメルケース」というルール)

$cureStar = "マイアミピンク";

$cureMilky = "青緑";

$cureSoleil = "黄色";

$cureSelene = "紫";

$cureCosmo = "虹色・青";

</pre>

プログラムが統一され綺麗になり、非常に読みやすくなりました。

これは他人が見ても [marker color="green"]そういうルールなのか[/marker] と気づきやすくなる効果もあります。

コメントを書く

プログラムが書けるようになると書くことに精一杯になり他人が読むことを意識しないプログラムが出来上がります。

この時、大事なことは明日の自分は他人であり他人が自分と同じだけプログラムが読み書きできると思わないことです。

私は仕事で様々な言語や現場を経験しましたが、コメントが書けない人が本当に多いです。
コメントは自分のためではなく他人のために残すものと考えましょう。

コメントを残すことでプログラムを読まなくても何をしているかがザックリとわかるようになります。
逆に何をしているかよくわからないとなってしまうコメントはNGです。


<!--?php 
    /**
     * 商品コードから生産地・在庫をチェック
     *
     * @param string $shohinCode 商品コード
     * @return boolean(true:チェックOK, false:エラー)
     */
    function checkShohin($shohinCode)
    {
        const PREFIX_SHOKUHIN = 1;
        const PREFIX_ZAKKA = 2;

        // 先頭1文字で処理を分岐
        //   1(食品) : 生産地をチェック
        //   2(雑貨) : 在庫確認
        //   その他: エラー
        $prefixShohinCode = mb_substr($shohinCode, 0, 1);
        if($prefixShohinCode == PREFIX_SHOKUHIN) {
            return checkSeisanchi($shohinCode);
        }
        else if($prefixShohinCode == PREFIX_ZAKKA) {
            return checkZaiko($shohinCode);
        }
        else {
            return false;
        }
    }

    // パラメータを取得
    $shohinCode = $params['shohinCode'];

    // 商品コードから生産地・在庫をチェック
    $checkResult = checkShohin($shohinCode);
</pre>
<p>関数の中身がどうなってるか分からなくても、何をしているか何となくわかりますよね？<br ?-->
あくまで一例ですので「このコメントではよくわからない」と思う人もいると思います。
ただ、こうやってコメントを残すことで、プログラムを読まなくても、ある程度読み取ることができます。

<!--?php

/**

* 商品コードから生産地・在庫をチェック

* @param string $shohinCode 商品コード

* @return boolean(true:チェックOK, false:エラー)

function checkShohin($shohinCode)

{

const PREFIX_SHOKUHIN = 1;

const PREFIX_ZAKKA = 2;

// 先頭1文字で処理を分岐

// 1(食品) : 生産地をチェック

// 2(雑貨) : 在庫確認

// その他: エラー

$prefixShohinCode = mb_substr($shohinCode, 0, 1);

if($prefixShohinCode == PREFIX_SHOKUHIN) {

return checkSeisanchi($shohinCode);

}

else if($prefixShohinCode == PREFIX_ZAKKA) {

return checkZaiko($shohinCode);

}

else {

return false;

}

// パラメータを取得

$shohinCode = $params['shohinCode'];

// 商品コードから生産地・在庫をチェック

$checkResult = checkShohin($shohinCode);

</pre>

関数の中身がどうなってるか分からなくても、何をしているか何となくわかりますよね？

あくまで一例ですので「このコメントではよくわからない」と思う人もいると思います。

ただ、こうやってコメントを残すことで、プログラムを読まなくても、ある程度読み取ることができます。

スコープの範囲を小さく保つ

ここで言うスコープとは変数の有効範囲のことを指します。
このスコープの範囲を大きくしてしまうと、思わぬところで不具合が発生してしまう原因となります。
どういうことか、例を見ていきましょう。


<!--?php 
    $title = "期末テスト採点";

    // チェックする点数を設定
    $checkScore = 30;

    // テストデータを取得し、採点結果を設定
    $testList = getTestList();
    for($i = 0; $i < count($testList); $i++) {
        $score = saiten($testList[$i]);
        $isAkaten = false;
        if($score < $checkScore) {
            $isAkaten = true;
        }
        $testList[$i]['score'] = $score;
        $testList[$i]['isAkaten'] = $isAkaten;

        $title = "採点結果";
        $testList[$i]['title'] = $title;
    }

    echo $title;
</pre>
<p>さて、画面には何が表示されるでしょうか？</p>
<p>&nbsp;</p>
<p>答えは 「[marker color="yellow"]採点結果[/marker]」 というテキストですね。</p>
<p>&nbsp;</p>
<p>でも本当に表示したかったのは [marker color="green"]期末テスト採点[/marker] というタイトルでした。<br ?-->
これは [marker weight="bold"]変数の初期化と出力の範囲が広すぎた[/marker] 事による不具合の発生です。

<!--?php

$title = "期末テスト採点";

// チェックする点数を設定

$checkScore = 30;

// テストデータを取得し、採点結果を設定

$testList = getTestList();

for($i = 0; $i < count($testList); $i++) {

$score = saiten($testList[$i]);

$isAkaten = false;

if($score < $checkScore) {

$isAkaten = true;

}

$testList[$i]['score'] = $score;

$testList[$i]['isAkaten'] = $isAkaten;

$title = "採点結果";

$testList[$i]['title'] = $title;

}

echo $title;

</pre>

さて、画面には何が表示されるでしょうか？

答えは「[marker color="yellow"]採点結果[/marker]」というテキストですね。

でも本当に表示したかったのは [marker color="green"]期末テスト採点[/marker] というタイトルでした。

これは [marker weight="bold"]変数の初期化と出力の範囲が広すぎた[/marker] 事による不具合の発生です。

この例のように短いものではほとんど発生しませんが、プログラムが肥大化していくほど、この問題にぶつかる可能性が大きくなります。
こういう事故にあわないためにも、スコープの範囲を意識し、可能な限り小さく保つように意識しましょう。

先ほどのプログラムは下記のように直すとスコープの範囲が小さくなります。


<!--?php 
    // チェックする点数を設定
    $checkScore = 30;

    // テストデータを取得し、採点結果を設定
    $testList = getTestList();
    for($i = 0; $i < count($testList); $i++) {
        $score = saiten($testList[$i]);
        $isAkaten = false;
        if($score < $checkScore) {
            $isAkaten = true;
        }
        $testList[$i]['score'] = $score;
        $testList[$i]['isAkaten'] = $isAkaten;

        $title = "採点結果";
        $testList[$i]['title'] = $title;
    }

    // $titleの有効範囲が2行だけに小さくなる
    $title = "期末テスト 採点";
    echo $title;
</pre>
<h3>コピペをしないで手打ちする（写経の卒業)</h3>
<p>初心者のうちは本やインターネットで調べた内容をそのままコピー＆ペーストをすることで動くプログラムを作る方が大半だと思います。<br ?-->
しかし、コピー＆ペーストは [marker weight="narrow" color="green"]プログラムが書けるようになる[/marker] わけではなく [marker weight="narrow" color="blue"]調べる力が付く[/marker] だけです。

<!--?php

// チェックする点数を設定

$checkScore = 30;

// テストデータを取得し、採点結果を設定

$testList = getTestList();

for($i = 0; $i < count($testList); $i++) {

$score = saiten($testList[$i]);

$isAkaten = false;

if($score < $checkScore) {

$isAkaten = true;

}

$testList[$i]['score'] = $score;

$testList[$i]['isAkaten'] = $isAkaten;

$title = "採点結果";

$testList[$i]['title'] = $title;

}

// $titleの有効範囲が2行だけに小さくなる

$title = "期末テスト採点";

echo $title;

</pre>

<h3>コピペをしないで手打ちする（写経の卒業)</h3>

初心者のうちは本やインターネットで調べた内容をそのままコピー＆ペーストをすることで動くプログラムを作る方が大半だと思います。

しかし、コピー＆ペーストは [marker weight="narrow" color="green"]プログラムが書けるようになる[/marker] わけではなく [marker weight="narrow" color="blue"]調べる力が付く[/marker] だけです。

調べる力が付いたら、次は自分でプログラムを書きましょう。

具体的にはコピー＆ペーストしたプログラムを1行ずつ調べていくということが良いと思います。

プログラムの詳細を調べていくことで、その命令は何をしているのか・何ができるのかをゆっくり自分で咀嚼(そしゃく)できます。
咀嚼した後、今度はコピー＆ペーストをせず、自分の力でプログラムを書いてみましょう。

その際、わからない場合は各言語の公式ドキュメント(マニュアル) を見るようにしましょう。
何故ならインターネットにアップされているプログラムが正しく動く保証はないからです。

ここまで出来た時が本当の意味でのプログラムを理解したということだと思います。

記事執筆時点での各言語の公式ドキュメント
C 言語リファレンス – Microsoft Docs –
C# リファレンス – Microsoft Docs –
C++ 言語リファレンス – Microsoft Docs –
PHPマニュアル – PHP –
Python 3.7.4 ドキュメント – Python –

アノテーションを使い分ける

アノテーションとは、一言で言うと注釈です。
プログラムを書いている時「メモを残しておきたい」「ここは後で修正しよう」といったことがあります。
そんな時、すべてコメントで書くのではなく、アノテーションを使いましょう。

アノテーションとは、「注釈」という意味の英単語で、ITの分野ではデータやプログラムの中に特殊な記法を用いて埋め込まれた付加情報のことをこのように呼ぶことが多い。
アノテーション – T用語辞典 e-Words –

悪い例


<!--?php 
    $age = getUserAge($userId);

    //@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
    // 2022年からは18歳以上が成人となるため、変更すること！
    //@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
    if($age < 20) {
        echo '未成年の方は保護者の同意が必要です。';
    }

    //=- 不具合あり =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
    // getUserGenderには不具合があるため、あとで修正する
    //=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
    $gender = getUserGender($userId);
    if($gender == "male") {
        echo "男性";
    } else {
        echo "女性";
    }
</pre>
<p>ブロックコメントでの識別や特定キーワードで意味を持たせるオレオレルールは好ましくありません。<br ?-->
他の人には伝わりませんので、プログラムを見た人は結局書いた人に聞くことになり、無駄が発生します。

<!--?php

$age = getUserAge($userId);

//@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

// 2022年からは18歳以上が成人となるため、変更すること！

//@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

if($age < 20) {

echo '未成年の方は保護者の同意が必要です。';

}

//=- 不具合あり =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

// getUserGenderには不具合があるため、あとで修正する

//=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

$gender = getUserGender($userId);

if($gender == "male") {

echo "男性";

} else {

echo "女性";

}

</pre>

ブロックコメントでの識別や特定キーワードで意味を持たせるオレオレルールは好ましくありません。

他の人には伝わりませんので、プログラムを見た人は結局書いた人に聞くことになり、無駄が発生します。

良い例


<!--?php 
    $age = getUserAge($userId);

    // TODO: 2022年からは18歳を成人とする
    if($age < 20) {
        echo '未成年の方は保護者の同意が必要です。';
    }

    // FIXME: getUserGenderに不具合あり
    $gender = getUserGender($userId);
    if($gender == "male") {
        echo "男性";
    } else {
        echo "女性";
    }
</pre>
<p>プログラムの言語ごとにアノテーションは大まかに決まっていますので、それを使用するようにしましょう。<br ?-->
対象箇所の検索や意味などを説明しなくてもすぐ理解ができるようになっています。
また、エディタによってはアノテーションを抽出する機能があるものもありますので、非常に便利になります。

<!--?php

$age = getUserAge($userId);

// TODO: 2022年からは18歳を成人とする

if($age < 20) {

echo '未成年の方は保護者の同意が必要です。';

}

// FIXME: getUserGenderに不具合あり

$gender = getUserGender($userId);

if($gender == "male") {

echo "男性";

} else {

echo "女性";

}

</pre>

プログラムの言語ごとにアノテーションは大まかに決まっていますので、それを使用するようにしましょう。

対象箇所の検索や意味などを説明しなくてもすぐ理解ができるようになっています。

また、エディタによってはアノテーションを抽出する機能があるものもありますので、非常に便利になります。

ただし、間違ってもどれを使えばわからないから全部TODOにしちゃえといったことはご法度です。
アノテーションの意味がなくなってしまいますからね。

アノテーションについてはよくまとめられているサイトもありますので、一読されてみてはいかがでしょうか？

TODO: 以外のアノテーションコメントをまとめた – Qiita –

「かっこ良い」より「わかりやすい」を優先する

他人のプログラムを見ていると「かっこ良い書き方だな」と思うことがあるかと思います。
しかし、そのかっこいい書き方のプログラムは果たして読みやすいでしょうか？
例を見てみましょう。

悪い例


<!--?php 
    $price = 1700;

    $msg = (2000 < $price) ? "送料無料" : ((1000 <= $price) ? "あと".(2000-$price)."円で送料無料です" : "送料がかかります");

    echo $msg;
</pre>
<p>これを見てすぐに何が表示されるかわかる人は少ないと思います。<br ?-->
また、デバッグ(プログラムをテストすること)の時、[marker weight="bold" color="yellow"]テスト漏れが発生する可能性[/marker]があります。

<!--?php

$price = 1700;

$msg = (2000 < $price) ? "送料無料" : ((1000 <= $price) ? "あと".(2000-$price)."円で送料無料です" : "送料がかかります");

echo $msg;

</pre>

これを見てすぐに何が表示されるかわかる人は少ないと思います。

また、デバッグ(プログラムをテストすること)の時、[marker weight="bold" color="yellow"]テスト漏れが発生する可能性[/marker]があります。

これはもっとわかりやすくした方が良いです。

良い例


<!--?php 
    $price = 1700;

    $msg = "";
    if(2000 < $price) {
        $msg = "送料無料";
    }
    else if(1000 <= $price) { $msg = "あと".(2000-$price)."円で送料無料です"; } else { $msg = "送料がかかります"; } echo $msg; ?-->

<!--?php

$price = 1700;

$msg = "";

if(2000 < $price) {

$msg = "送料無料";

}

else if(1000 <= $price) { $msg = "あと".(2000-$price)."円で送料無料です"; } else { $msg = "送料がかかります"; } echo $msg; ?-->

これで初心者が見てもわかりやすいif文になりました。
また、どうやってテストをすれば良いかも一目でわかります。

どれだけかっこ良いプログラムを書いても利用者には全然伝わりませんので、プログラムにカッコ良さは二の次というわけです。

カッコ良いプログラマとは、カッコ良いプログラムが書けるのではなく「不具合を出さないようにプログラムを作る」人のことではないでしょうか。

さいごに

ここまで長々と書きましたが、すべてを実践する必要はありません。
最初に書きましたが共感・納得できると思った事から始めてみると良いと思います。

カッコ良いエンジニアを目指していきましょう！

おすすめ記事

POPULAR

プログラム

のえる

Full-stack Developer

記事一覧

【すぐできるチャットボット】「Talk API」を使った作り方

たった5分でPHPのファイルアップロードを作る方法

のえる

Full-stack Developer

お休みはゲーム三昧。目指すは生涯自由人。ツナ缶大好き。

記事一覧

初心者を卒業！現役が教えるプログラミング上達方法

はじめに

環境編

タブとスペース(半角/全角)を混在しない

エディタのカラーテーマを設定する

書き方を統一する（コーディング規約を作る）

コメントを書く

スコープの範囲を小さく保つ

アノテーションを使い分ける

「かっこ良い」より「わかりやすい」を優先する

さいごに

イラストレーターで座標に変な小数点が入ったときに消す方法

WebブラウザからWindowsアプリケーションを開く[追記あり]

PHPで日付をフォーマットするならCarbonを使おう

node.js のアプリを永続化(デーモン化)させる

iPadアプリがフルスクリーンにならない

WindowsのDockerでMySQLが起動しない

初心者を卒業！現役が教えるプログラミング上達方法

はじめに

環境編

タブとスペース(半角/全角)を混在しない

エディタのカラーテーマを設定する

書き方を統一する（コーディング規約を作る）

コメントを書く

スコープの範囲を小さく保つ

アノテーションを使い分ける

「かっこ良い」より「わかりやすい」を優先する

さいごに

jQueryはもう不要？2019年のフロントエンド事情を考えてみる

【初心者あるある】プログラミングを始めて２ヶ月の初心者が思うこと

イラストレーターで座標に変な小数点が入ったときに消す方法

WebブラウザからWindowsアプリケーションを開く[追記あり]

PHPで日付をフォーマットするならCarbonを使おう

PHPのセッションが勝手に消えてしまう問題と解決法

イラストレーターで座標に変な小数点が入ったときに消す方法

WebブラウザからWindowsアプリケーションを開く[追記あり]

PHPで日付をフォーマットするならCarbonを使おう

node.js のアプリを永続化(デーモン化)させる

iPadアプリがフルスクリーンにならない

WindowsのDockerでMySQLが起動しない