第四章

本章では,プログラミング言語自体が豊富な表現力を持っていれば,注釈は必要ないと述べる.
コメントは、コード表現の失敗を意味します.このように、あるいは作者が注釈を無視したのは、注釈がよく嘘をついているからだ.注釈が長くなるほど、コードから遠くなります.ますますメンテナンスが難しくなりました.

MockRequest request;
private final String HTTP_DATE_REGEXP = "[SMTWF][a-z]{2}\\,\\s[0-9] ...
private Response response;
private FitNesseContext context;
private FileResponder context;
private Locale saveLocale;
// Example: "Tue, 02 Apr 2003 22:18:49 GMT"

上記の例では、コメントとHTTP DATE REGEXPの間に新しいフィールドが追加される予定です.
注釈はHTTP DATE REGEXPについての内容ですから.
そのため、コメントは厳格に管理され、リカバリ性、相関性、正確性が常に高い必要があります.
しかし、著者は注釈を書かない方向にエネルギーを投入することを提案した.

注記悪いコードを補うことはできません

コードに注釈を含める一般的な原因は、コードの品質が悪いことです.
表現力が豊富で、簡潔で、注釈がほとんどないコードは、複雑で、乱れていて、注釈の多いコードよりずっと良いです.

コードで意図を表す!

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flag & HOURLY_FLAG) && *employee.age > 65))

if (employee.isEligibleForFullBenefits())

上記のコードでは,2つの構文の下半分が注釈を用いずに意図をよりよく表現していると考えられる.

よい議長

本当に良い注釈は注釈をつけない方法を見つけた注釈です.
しかし、一部の注釈は必要または有益である.その良い注釈は以下の通りです.

-法的コメント

著作権情報または所有権情報は必要かつ妥当である.

//Copyright (C) 2003,2004,2005 by Object Mentor, Inc. Al;l rights reserved.
...

-情報を提供するコメント

基本情報を注釈として提供すると便利になる場合があります.

例1

// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

ただし、上記のコメントをResponderBeingTestedに変更した場合、コメントは不要です.

例2

// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*,\\w* \\d*, \\d*");

上記のコードがそうである以上、視点と日付を変換するクラスを作成してコードを移動することができ、コードがよりよく、よりきれいになり、コメントを必要としません.

-意図を説明するコメント

注記は、理解の実現を助ける限界を超えたり、決定に設定された意図を説明したりすることもあります.
ex)2つのオブジェクトを比較するときに他の任意のオブジェクトよりも優先されるコードのコメントを説明します.

-意味を説明するコメント

一般に、引数または戻り値自体を明確にすると良いですが、引数または戻り値が標準ライブラリまたは変更できないコードに属している場合は、その意味を説明するコメントが役立ちます.

例

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != a
assertTrue(ab.compareTo(ab) == 0); // ab == ab

-警告結果のコメント

他のプログラマーに結果を警告するためにも使用されます.
たとえば、「十分な空き時間がない場合は、実行しないでください」コメント付きテストケース
あまり時間がないプログラマーにとって、これは良いヒントかもしれません.

-ODOコメント

「これからやること」を//ODO議長に残すのは便利です.TODO会長はプログラマーが必要だと考えているが,すぐには実施しにくい業務について述べている.

は、不要な機能の削除を通知する

である.

質問

もっと良い名前を考え出してください

は、将来のイベントに適応するためにコードを変更することを警告します.たとえば、

ただし、TODOで色を塗るコードは理想的ではなく、定期的にTODOコメントをチェックすべきです.

-重要性を強調するコメント

重要性を強調するために注釈も使用します.

-公開APIでのJavadocsの使用

適切に説明された公開APIは有用で満足できるものである.標準javaライブラリで使用されるJavadocsは良い例です.ただし、他のコメントと同様に、誤った情報が提供される可能性があります.

悪いコメント

ほとんどのコメントはこのカテゴリに属します.多くの注釈はプログラマーのくどくどした独白にすぎない.例えば、ばらばらなコードを支持したり、ばらばらなコードを弁解したり、未熟な決定を合理化したりする.

-うるさいコメント

例

public void loadProperties()
{
	try
	{
        String propertiesPath = propertiesLocation + "/" PROPERTIES_FILE;
        ...
	}
    catch(IOException e)
    {
    	//속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미다.
    }
}

catchブロックの注釈は著者のみが知っており,他の人には伝えられない.

デフォルト値をすべて取得するのは誰ですか?

loadProperties.loadを呼び出す前に取得しますか?

loadProperties.loadはファイルを取得する前にすべてのデフォルト値を取得しますか?

作者はまたいくつかの文を補充して、どうしてcatch blockを出しますか?

または後でデフォルト値を取得するコードを作成しますか?

知る由もないコードを調べなければなりません.
理解できないために他のモジュールの注釈をめくる必要があるのは,読者と正しくコミュニケーションできない注釈である.

-同じ内容のコメントを繰り返す

例

//this.closed가 true일 때 반환되는 유틸리티 메서드다.
//타임아웃에 도달하면 예외를 던진다.
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
if(!closed)
{
	wait(timeoutMillis);
    if(!closed)
      	throw new Exception("MockReponseSender could not be closed");
    }
}

上のコードのコメントは、コードよりも多くの情報を提供することができず、同じ話を繰り返しています.

-誤解の可能性があるコメント

上記の例では、this.closedがtrueになると、メソッドは返されません.
this.closedはtrueであり、メソッドは半限定であり、そうでなければ待機タイムアウトである.closedがtrueでない場合、例外が投げ出されます.
注記この状況は説明できません.そのため、プログラマによっては、この関数を誤って理解して使用する場合があります.

-義務コメント

すべての関数にJavadocsを無条件に組み込むルールは正しくありません.逆にコードを混同させるだけで、エラーも情報を提供する余地しかありません.

-履歴コメント

以前はソース管理システムがなかったため、コメントに修正履歴が記録されています.ただし、変更履歴をコメントに記録するのは適切ではありません.

-コメントがあるかどうかにかかわらず

/**
* 기본생성자
**/
protected AnnualDateRule{}

/** 월 중 일자 */
private int dayOfMonth;

/**
* 월 중 일자를 반환한다.
*
* @return 월 중 일자
*/
public int getDayOfMontH() {
	return dayOfMonth;
}

コメントよりも、関数を分離したり、コード構造を明確に命名したり、改善したりします.

-ひどい騒音だ

Javadocsも雑音である場合があります.Javadocsを使用する場合は、徹底的に管理します.

-関数または変数で表示できる場合はコメントを付けない

例

// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if(smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

改良

ArrayList moduleDependees = smodule.getDependSubsystems();
String oourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubsystem))

注釈を使わずにコードをうまく表現できます.

-場所のコメントを表示

注記:ソースファイル内の特定の場所を表示します.
ex)

// Actions /////////////////////////

目立つ注意喚起の役割を果たしていますが、必要なときだけ、あまり使わないほうがいいでしょう.
バナー広告を乱用すると、読者はよくある雑音だと思って無視するかもしれません.

-右かっこのコメント

右かっこにコメントを付けるよりも、オーバーラップを減らして関数を減らしてみましょう.

-著者のコメントをエスケープまたは表示します。

/* 릭이 추가함 */

この注釈は長い間続いていて,次第に不正確になってきた.これらの情報は、ソースコード管理システムに格納することが望ましい.

-コメントコード

コメント処理されたコードは他の人に消去されます.

理由があって残ったのでしょう

重要削除できないでしょ

これらの理由で、不要なコードが増えています.
ソースコード管理システムは私たちのためにコードを覚えています.大胆に消して

-HTMLコメント

それが自分を嫌っている.HTMLコメントは、コメントを読む必要があるIDEでも読みにくい.

-グローバル情報

コメントが必要な場合は、近くのコードのみを説明する必要があります.システム全体の情報を記述するために、一部のコードに注釈を付けないでください.

/*
*  적합성 테스트가 동작하는 포트 : 기본값은 <b>8082</b>.
*
* @param fitnessePort
*/
public void setFitnessePort(int fitnessePort)
{
	this.fitnessPort = fitnessePort;
}

この関数では、ポートのデフォルト値を制御できません.デフォルトのポート値が変更されている場合は、コメントが変更され、エラーメッセージが表示されることは保証されません.

-情報が多すぎる

注釈に面白い歴史や関連のない情報を羅列しないでください.

-ファジイ関係

コメントとコメントが記述するコードは、両者の関係を明確にする必要があります.
読者は注釈とコードを読んで、どういう意味か知っているはずです.

/*
* 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다.).
*  ...
*/
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];

ここのフィルタバイトは何ですか?+1? *3?

ピクセルは1バイトですか?

なぜ

200を追加しますか?

議長自身が再説明を要求した.

-関数タイトル

短い関数には長い説明は必要ありません.短くて精巧で命名された関数は、注釈にタイトルを付けた関数よりもずっと優れています.

-専用コードでJavadocsを使用

Javadocsは役に立ちますが、公開されていないコードではJavadocsは役に立ちません.