CODEWITHSUNDEEP
javaeclipsecommentsenterprise
Farmer
Farmer

Reputation: 10983

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 name="username">The user password</param>
// <returns></returns>
public Connect(int id, String password)
{

}

Thanks already.

Upvotes: 2

Views: 20483

Answers (10)

Darshan Shah
Darshan Shah

Reputation: 11

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
 */

Upvotes: 0

Thiib
Thiib

Reputation: 39

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

Upvotes: 1

Brian
Brian

Reputation: 6450

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.

Upvotes: 7

bazza2000
bazza2000

Reputation: 141

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

Upvotes: 2

Andrey Adamovich
Andrey Adamovich

Reputation: 20663

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

Upvotes: 1

wjans
wjans

Reputation: 10115

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.

Upvotes: 10

Tapas Bose
Tapas Bose

Reputation: 29806

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

Upvotes: 2

Mathias Schwarz
Mathias Schwarz

Reputation: 7197

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.

Upvotes: 4

denis.solonenko
denis.solonenko

Reputation: 11775

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) {...}
}

Upvotes: 1

spot35
spot35

Reputation: 888

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.

Upvotes: 1

Related Questions