抽象メソッドに対するコメントを、具体的にしすぎない【178日目】

抽象メソッドって？

abstract class ClassHuman
{
    abstract protected sayGreeting();
}

この abstract protected sayGreeting();の部分。

これは、実装が描かれていないので、

class ClassJapanese extends ClassHuman
{
    protected sayGreeting()
    {
        echo 'こんにちは！';
    }
}

のように、継承先で実装を行う。

コメントを具体的にしない？

abstract class ClassHuman
{
    // こんにちはと文字を出力する
    abstract protected sayGreeting();
}

これだと困るのがわかると思います。
継承先は、 echo 'こんにちは';とか、DBに'こんにちは'とか、実装がすっごく狭まります。

そもそもsayGreetingは本当に『こんにちは』と言わせたかったの？

挨拶をさせたかったのでは？

させたかったことは『挨拶をさせる』です。

abstract class ClassHuman
{
    // 挨拶を出力させる
    abstract protected sayGreeting();
}

class ClassJapanese extends ClassHuman
{
    protected sayGreeting()
    {
        echo 'こんにちは！';
    }
}

class ClassAmerican extends ClassHuman
{
    protected sayGreeting()
    {
        echo 'Hello！';
    }
}

これなら、違和感ないと思います。

何をさせたいのかを抽象的に考える

『こんにちは』と言わせたい
挨拶をさせたい

それぞれ、意味の範囲も違います。
前者は具体的過ぎますし、このクラスを継承させる時に、全部のクラスに本当に『こんにちは』を言わせたいのかをよく考える必要があります。

必要十分なコメントを書くことが重要であると言われたことがあります。

なかなかその領域になれていませんが、
コメントで詳しく言い過ぎ、定義広げすぎとならないように、
今後も注意してコメントを書きたいです。

じゃないと、上の例みたいに、コメントが関数を十分に表現できず、
コメントによってプログラムが制約されてしまうので、
気をつけていきましょう。