title: Default comments and meta-information in Java classes/interfaces
body: <p>In some codebases I saw comments that can be described as <em>default comments</em>. These comments you normally will find in every file of the project and, I believe, in most cases they are automatically generated with the help of IDE. Meta-information is a little bit different. It's actually part of the code. I think I'd better show this on example. This is our test subject (taken from real life and simplified):</p>
  
  <pre><code>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&lt;User&gt; getUserById(final Integer id) {
          return userDao.getUserById(id);
      }
  
      /**
       *
       * @see IUserService#getUserList(IEnvironmentContext)
       */
      @Override
      public List&lt;User&gt; 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 {...}";
      }
  }
  </code></pre>
  
  <p>This class contains a lot of concepts I want to discuss, so I split them in these types:</p>
  
  <p><strong>1) Section default comments</strong> - for each section of the class there is one 3-line comment (like constants, constructors, ...). Please note, that I'm not talking about logical sections of class (like <code>// user managenet</code> or <code>// Account Balance calculation</code>).</p>
  
  <p><strong>2) Getter and Setter default comments</strong> - comments for set/get methods that just tell that correspondent method sets of returns field value.</p>
  
  <p><strong>3) Meta comments</strong> - comments that describe meaning of some java language constructs. Examples from above: <code>@see IUserService#saveUser(User)</code> - tells that method is overridden/implemented and location of parent method, <code>Default constructor</code> - tells that it's default constructor of Java class, <code>Logger for this class</code>.</p>
  
  <p><strong>4) @SuppressWarnings("unused")</strong> - in my concrete example it used to say, that <code>LOG</code> is not used in the class (<code>LOG</code> is really never used in the class, but IDE will not show warning) and <code>context</code> argument is not used, but it's OK (assuming that <code>context</code> is some general information and it's generally completely normal if implementations do not use it).</p>
  
  <p><strong>5) <code>I</code> prefix for interfaces</strong> - prefix tells, that this is interface. </p>
  
  <p><strong>6) <code>final</code> for method arguments</strong> - prevents code in method body to change it's value</p>
  
  <p><strong>I would like to know your opinion about default comments and meta-information in classes.</strong> In order to make it more straightforward I propose you to vote  for each type with grades from +5 down to -5:</p>
  
  <p><strong>+5</strong> - I think it's <strong>must</strong> and it's should be done by every Java developer and should even be enforced with tools (like checkstyle) <br>
  ... <br>
  <strong>0</strong> - I don't care. If somebody will tell me to do it, I will - these comments will not bring any positive or negative value. <br>
  ... <br>
  <strong>-5</strong> - I strongly discourage everybody to make this. Such default comments/meta-information should be deleted from class as soon as you see it. <br></p>
  
  <p>I also strongly believe, that it's very important always to explain you option and answer question: why do you think so? (I personally try always to follow this rule). So I also encourage you to explain points you have given for particular type.</p>
  
  <p>I will accept answer with most SO up-votes in about one week.</p>
  
  <p><strong>PS.:</strong> Some of you may think that answer is self-evident, but believe me, each of us is very different and something that is self-evident for you can be surprise for me and vice versa. So I encourage you to participate this discussion anyway. (I will appreciate this)</p>