Javaクラス/インタフェースのデフォルトのコメントとメタ情報

Question

一部のコードベースでは、のデフォルトコメントと記述できるコメントがありました。これらのコメントは通常、プロジェクトのすべてのファイルにあります。私は、ほとんどの場合、IDEの助けを借りて自動的に生成されると信じています。メタ情報は少し異なります。実際にはコードの一部です。私はこれを例にして見せたいと思う。これは、（現実の生活と簡略化から取られた）我々のテスト対象である：

public class UserServiceImpl implements IUserService { 

    //////////////////////////////////////////////////////////////////////// 
    // Constants 
    //////////////////////////////////////////////////////////////////////// 

    /** Logger for this class */ 
    @SuppressWarnings("unused") 
    private static final Log LOG = LogFactory.getLog(UserServiceImpl.class); 

    //////////////////////////////////////////////////////////////////////// 
    // Attributes 
    //////////////////////////////////////////////////////////////////////// 

    /** User DAO */ 
    private IUserDao userDao; 

    //////////////////////////////////////////////////////////////////////// 
    // Constructors 
    //////////////////////////////////////////////////////////////////////// 

    /** 
    * Default constructor 
    */ 
    public UserServiceImpl() { 
    } 

    public UserServiceImpl(final IUserDao userDao) { 
     this.userDao = userDao; 
    } 

    //////////////////////////////////////////////////////////////////////// 
    // Getter and Setter methods 
    //////////////////////////////////////////////////////////////////////// 

    /** 
    * @return value of {@link #userDao} field 
    * 
    */ 
    public IUserDao getUserDao() { 
     return userDao; 
    } 

    /** 
    * Sets {@link #userDao} field 
    * 
    * @param userDao User DAO 
    */ 
    public void setUserDao(final IUserDao userDao) { 
     this.userDao = userDao; 
    } 

    //////////////////////////////////////////////////////////////////////// 
    // Implemented/Overridden methods 
    //////////////////////////////////////////////////////////////////////// 

    /** 
    * 
    * @see IUserService#saveUser(User) 
    */ 
    @Override 
    public void saveUser(final User user) { 
     fillMissingFields(user); 
     userDao.saveUser(user); 
    } 

    /** 
    * 
    * @see IUserService#getUserById(Integer) 
    */ 
    @Override 
    public List<User> getUserById(final Integer id) { 
     return userDao.getUserById(id); 
    } 

    /** 
    * 
    * @see IUserService#getUserList(IEnvironmentContext) 
    */ 
    @Override 
    public List<User> getUserList(final @SuppressWarnings("unused") IEnvironmentContext context) { 
     return userDao.getUserList(); 
    } 

    //////////////////////////////////////////////////////////////////////// 
    // Helper methods 
    //////////////////////////////////////////////////////////////////////// 

    private void fillMissingFields(final User user) { 
     user.setLastUpdated(new Date()); 
    } 

    //////////////////////////////////////////////////////////////////////// 
    // toString() method 
    //////////////////////////////////////////////////////////////////////// 

    /** 
    * 
    * @see Object#toString() 
    */ 
    @Override 
    public String toString() { 
     return "UserServiceImpl {...}"; 
    } 
} 

このクラスは、私が議論したい概念の多くが含まれているので、私はこれらのタイプでそれらを分割：

1）セクションのデフォルトコメント - クラスの各セクションには、3行のコメント（定数、コンストラクタなど）が1つあります。クラスの論理セクション（// user managenetまたは// Account Balance calculationなど）については言及していません。

2）ゲッターとセッターのデフォルトコメント - リターンフィールド値の対応するメソッドセットだけを伝えるset/getメソッドのコメント。

3）メタコメント - いくつかのJava言語構造の意味を説明するコメント。上記の例：@see IUserService#saveUser(User) - メソッドがオーバーライドされ/実装され、親メソッドの位置がDefault constructor - Javaクラスのデフォルトのコンストラクタであることを示します。Logger for this class。

4）@SuppressWarnings（「未使用」） - ）私の具体的な例では、それはLOGはLOGが本当にクラスで使用されることはありません（クラスで使用されていないことを、言って使用されるが、IDEは警告が表示されませんとcontext引数は使用されませんが、それは正常です（contextが一般的な情報であると仮定し、実装がそれを使用しない場合は一般的に完全に正常です）。

5）I接頭辞 - 接頭辞は、インターフェイスであることを示します。メソッドの引数ため

6）finalは - それは、私はクラスのデフォルトのコメントやメタ情報についてのご意見をお知りになりたい値

です変更するメソッド本体のコードを防ぐことができます。はそれをより簡単にするために、私はあなたが-5まで5からのグレードと、各タイプのために投票することを提案する：

- 私はそれが必見だと思うし、それは、すべてのJava開発者によって行われる必要があります
...
- 私は気にしません。もし誰かが私にそれを言うと言えば、私はします - これらのコメントは正または負の価値をもたらさないでしょう。
...
-5 - 私は誰もがこれを作ることを強く勧めます。そのようなデフォルトのコメント/メタ情報は、あなたがそれを見てすぐにクラスから削除されるべきです。

私は強く、常にあなたにオプションを説明し、質問に答えることが非常に重要だと考えています。なぜそう思いますか？ （私は個人的に常にこのルールに従おうとします）。だから私はまた、あなたが特定のタイプについて与えたポイントを説明することをお勧めします。

私は約1週間で最大の票数で回答を受け付けます。

PS：あなたの中には、答えは自明であるが、私を信じて、私たちのそれぞれが非常に異なる、あなたは私とその逆のためにサプライズすることができためには自明である何かであると考えることがあります。とにかくこのディスカッションに参加することをお勧めします。 （私はこれを感謝するでしょう）