The best way to comment code in Java

What's the best way to comment code in Java, is there a way to generate the function name and the parameters automatically in Eclipse ?

For example I'm writting those comments manually :

// <summary>
// Some comments about the function
// </summary>
// <param name="id">the user ID</param>
// <param n开发者_如何学Pythoname="username">The user password</param>
// <returns></returns>
public Connect(int id, String password)
{

}

Thanks already.

Take a look at Javadoc

Javadocs can easily be generated in Eclipse. You can type /** and it will autocomplete. You can also configure your code templates to automatically generate javadocs.

Select the method for which you want comments and press SHIFT, ALT and J together.

Take the time to learn about JavaDoc as well it's a very rich area for documenting your code.

By convention this is the way to do it:

/** Some comments about the function
  * 
  * @param id the user ID
  * @param username The user password
  *
*/
public Connect(int id, String password)
{

}

If your method returns anything, you would add a `@return' followed by an explanation.

You IDE and the standard JavaDoc tool will be able to parse this.

I personally prefer to use JAutodoc plugin for commenting. Take a look at it. Its good.

There seems to be some confusion on this thread. The key sequence I use to generate javadoc comments is SHIFT+ALT+J not CTRL?

The best way is to use JavaDoc and eclipse has built in code templates for doing just that.

If you want to have the format you've shown here, then you can write your own templates. The templates functionality will allow you to insert variables, of which one will be the method name.

I'd say that the best way to comment code in java is to provide meaningful names for your methods and variables names :)

class MyService {
    public void authenticateUser(int userId, String userPassword) {...}
}

The best way is to use Javadoc comment format, not the one you shown in the question.

In Eclipse, put your cursor on the method name and press Ctrl+Alt+J. It will generate you a Javadoc comment with all parameters listed.

You can also control the way Javadoc comment is generated in Window -> Preferences -> Java -> Code Style -> Code Templates -> Comments

You need to press CTRL+ALT+J in same time having the cursor on the declaration row.

I would suggest to go with the shift+alt+j for Eclipse, and write the description of the function so that other developer can understand what the function can do and also this auto commenting functionality will provide the @param and @return attributes so that you can specify what should be needed and what should be expected in order to execute the function.

For Example:

/**
 * @param msg
 * will return the converted message from the byte[] msg
 * @return
 */