2014/07/23 このエントリーをはてなブックマークに追加 はてなブックマーク - ソースは英語で、コメントは意訳(Programing have to be like natural English, and comment have to be free translation)

ソースは英語で、コメントは意訳(Programing have to be like natural English, and comment have to be free translation)

カテゴリ: ,

スパゲティコード、レガシーコードなど
コーディングに関する情報や言葉というのは世の中にたくさんあります。



そういった言葉から、いつも感じるのは
可読性の重要性です。


また、それを守る事とは、最終的にはコードという「文章」を書く
というところに結びつくと僕は考えています。


コーディング規約に書かれている事のほとんどは「文章を書くこと」を具体的に言っている
だけなのではないかなと。イディオムに近いものだと思っています。


従って、英語を意識しながらコーディングすれば、
可読性が高く、自然と規約に沿った実装が出来るはずです。






僕は実装するときに、感覚的には英語のライティングと同じように、ソースを書いています。
ポイントとしては

  • 主語は何か
  • 動詞は何か
  • 前置詞は何か、補語は何か
  • 複数か単数か
  • どのような状態か

  • だと思っています。


    今回はJavaのクラスを1つ作ると想定して、「英文のような実装」というものを考えてみます。





      主語は何か


    Javaプログラミングにおいては往々にして、主語はクラスです。
    もう少し具体的に言うと、java.lang.Objectの派生クラス変数、インターフェース変数、プリミティブ変数などです。


    例えば、ドラえもんのクラスとか作っちゃいましょうか(笑)
    (藤子先生ごめんなさい)


     public class Draemon {
    
    }


      動詞は何か


    これはメソッド名を考える時に重要です。
    前述した主体が何をするか、と考えます。


    「ドラえもんは道具を取り出します。」

     public class Draemon {
        /**
         * 道具を取り出すメソッドです
         * @return 道具
         *
         */
        public MagicItem takeOutItem() {
            ....
            return new MagicItem();    
        }
    }



    英語にすると"Draemon takes out item."
    (3人称単数現在形のsはプログラミングでは慣習的に使わないような気がします。)




      前置詞は何か、補語は何か



    しかし、道具を取り出すだけだとJAFとかキテレツとなんら変わりありません。
    メソッドが抽象的になってしまいます。
    そんな時に考えるのは前置詞や補語。


    「ドラえもんは道具をポケットから取り出します」

     public class Draemon {
        /**
         * 道具を取り出すメソッドです
         * @return 道具
         */
        public MagicItem takeOutItemFromPocket() {
            ....
            return new MagicItem();    
        }
    }



    英語にすると
    "Draemon takes out item from pocket."



    もう少し掘り下げると、のび太君が「ドラえもん、タケコプター出してよ」
    といった場合にも前置詞や補語は重要です。
    良くあるパターンとしては、ByName、ByIdなど。
    これは英語的というよりはプログラミング英語です。


     public class Draemon {
        /**
         * 道具を取り出すメソッドです
         * @param itemName 道具の名称
         * @return 道具
         */
        public MagicItem takeOutItemFromPocketByName(String itemName) {
            ....
            return new MagicItem(itemName);
         }
    }



    英語にすると
    "Draemon takes out item from pocket by name."


    メソッドを実行する時としては
    "Draemon takes out item from pocket that name is 'スモールライト' "
    みたいな感じですかね。





    このようにすれば、道具の名前によって、ドラえもんが欲しいものを渡してくれるようになります。
    dcocument.getElementByIdとかfindViewByIdとかはこのパターンですね。






    ちなみに、ドラえもんが量産型ではないとするとstaticメソッドになります。
    もしくはSingletonパターンですかね。
    今回のエントリでは省略します。






      どのような状態を表すか



    常に状態というのは変化します。
    今は大丈夫、これはダメ、これはOK。
    プログラミングにおいても、日常においてもそうです。


    状態を表す動詞としてプログラミングでよく使われるのは
    can、have、has、isなどです。


    「ドラえもんはポケットを持っています。」




     public class Draemon {
        
        /** ドラえもんのポケット */
        private Pocket pocket;
    
        /**
         * ポケットの存在チェックをします 
         * @return ポケットが持っているどうか
         */
        public boolean hasPocket() {
            
            // ポケットを失くしていないか確認する
            if ( pocket.isMissing() ) {
                return false;
            }
            return true;
        }
    }



    簡潔にすると、こう。

     public class Draemon {
        
        /** ドラえもんのポケット */
        private Pocket pocket;
    
        /**
         * ポケットの存在チェックをします 
         * @return ポケットが持っているどうか
         */
        public boolean hasPocket() {
            
            // ポケットを失くしていないか確認する
            return !pocket.isMissing();
        }
    }


    英語にすると


    Draemon has pocket.


    ドラえもんにポケットというメンバ変数をつけてみました。
    メンバ変数は言って見れば、服や装備です。


    のび太君がポケットをメンバ変数に持っていては駄目なのです。
    (ズボンのポケットとかスペアポケットが、、、、とか言わないでね。。。。)

    のび太君にcryメソッドや射撃メソッドがあったとしても道具を取り出すメソッドを作ってはいけません。
    (これはオブジェクト指向で言うところの「カプセル化」です。多分。)


    しかしながら、英語的な
  • 主語は何か
  • 動詞は何か
  • 前置詞は何か、補語は何か
  • 複数か単数か
  • どのような状態を表すか

  • を意識していないコーディングは業務上のプログラミングでも溢れかえっており、
    混沌としているのです。


    例えるなら、
    ドラえもんが寝るのが得意、ドラミちゃんは男
    スネ夫は坊主頭、、見たいなミスマッチが多発しています。


    それほどにSVOC(主語、述語、目的語、補語)は大事です。









      コメントは意訳で




    続いて、ソースコメント。

    ソース中のコメントに関しては、

    プログラミング入門者は直訳、中上級者は意訳という意識で書いていくのが良いと思います。



    例えば、お粗末ですが、こんなソースの場合




    
    
    
     List<String, String> nameList = findList("人名");
    
    if ( nameList.size() > = 2) {
        String firstItemName = nameList.get(0);
        String secondItemName = nameList.get(1);
    
        if( firstItemName.equals(secondItemName)) { 
            doAnything();
        }
    }



    直訳パターン
    
    
    //  "人名"をキーにしてArrayListを取得
     List<String, String> nameList = findList("人名");
    
     // リストの要素が2つ 以上の場合
    if ( nameList.size() > = 2) {
        // 1つ目の値と2つ目の値を変数に格納
        String firstItemName = nameList.get(0);
        String secondItemName = nameList.get(1);
    
        // firstItemNameとsecondItemNameが等しいとき
        if( firstItemName.equals(secondItemName)) { 
            // 任意の処理
            doAnything();
        }
    }




    意訳パターン
    
    
    //  人名リストを取得
     List<String, String> nameList = findList("人名");
    
     // リストのサイズチェック
    if ( nameList.size() > = 2) {
        // 1つ目の値と2つ目の値を変数に格納
        String firstItemName = nameList.get(0);
        String secondItemName = nameList.get(1);
    
        // 1人目と2人目が重複している場合は任意の処理
        if( firstItemName.equals(secondItemName)) { 
            
            doAnything();
        }
    }





    この意訳パターンも微妙ですが、、笑
    こんな感じです。




    なんとなく伝わったでしょうか(笑)
    直訳型は悪い訳ではありません。
    プログラミングを覚えたての頃は1ステップ1ステップの意味を明確に理解するために
    直訳型のコメントを書いていく
    べきだと思います。


    コードだけで意味が分かるようになってきたら徐々に意訳パターンへ
    シフトすると良いのではないでしょうか。



    ポイントとして、意訳は実装の変更に強いです(少しだけ)。
    多少呼び出すメソッドが変わっても、行うべき処理をコメントとして
    簡潔に書いていれば良いのです。

    コメントだけでそこで何を行っているか分かるのがベストだと思います。



    あとあとソースの変更に寄ってコメントが意味をなさなくなるものは
    良くないソースコメントです。

    コメント書かない派とか、いろいろな方がいらっしゃるとは思いますが。。。









      英語として考える


    主語は何か。動詞は何か。前置詞は何か。補語は何か。複数か単数か。どのような状態をあらわすか。




      コーディング規約を守る=英語を書く。 英語を書く=コーディング規約を守る



    コーディング規約はルールだから守らなくては駄目というだけでは考えとしては浅いです。きっと。
    コードを表現上、自然言語に近づけるというのが本質だと思っています。
    そうすれば自ずと、コーディング規約を守る事になるのです。


    コーディング規約は表現のTips(種)だと思ってくれれば良いと思います。



      コメントは直訳からシフトし、意訳へ


    プログラミングを始めたての頃はステップごとの処理を記述していき
    中上級者になるにつれて、処理ブロックというか仕様や要件機能的な部分を
    書いていくと良いと思います。



    今回はこんなところです。
    初心者向けの気持ちで書きましたが、
    突っ込みどころは多いですね。いろいろなご意見クレームお待ちしています(笑)













    0 件のコメント:

    コメントを投稿

    GA