java - コメントについて統一したこと

Doxygen を使用するにあたって javaコメント を統一した時のメモ

1. ヘッダーコメント

test.java

/*
 *
 * @Title      : ${PACKAGE_NAME}
 * @Description:
 * @company    : ** corp
 * @history    : Created by ${USER} on ${DATE}.
 *
 */
public class ${PACKAGE_NAME} {
    /* constractor */
    ${PACKAGE_NAME} () {
        ...
    }
    ...
}

以上をテンプレートに入れておき、クラス作成時に自動入力します。
@Titleにクラス名を記載します
@Description にクラスの概略を記述します
@company に作成者、もしくは会社を記述します
@history に作成日、もしくはModified した日を記入します

2 メソッドコメント

test.java

/**
 *  @brief  This function is called by the application to add ...
 *  @param len  Length
 *  @param data Data
 *  @param src  Src
 *  @return     result
 *  @since      ticket no.
 */
private bool storeData(int len, int data, int src)
{
    ...
}

@brief に メソッドの概略を記載します
@param パラメータの詳細を記載します。データがどのような種類か、どんな範囲か記載すると後工程でわかりやすいです。
@return 返却値を記載します。これもデータの種類、範囲を記載するとわかりやすいです。

コメント生成ツールに登録しておき、自動で記入できるようにしておきます。
個人的にはVisual Studio Code が良いです。

3 プロパティコメント

一行一行に記載するのではなく、実行単位での記載とします

test.java

 // @summary The Name property ...

4 まとめ

自分的には、コメントはこのくらいゆるくしておいて、
後はDoxygenの設定でどうにかする派