• Post Reply Bookmark Topic Watch Topic
  • New Topic

Please help me understand using javadocs vs. traditional comments.  RSS feed

 
Will Klem
Greenhorn
Posts: 21
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
As a newbie, I am still using introductory resources to learn java programming. Unfortunately these resources give only passing reference to javadocs. Research on my part has given me a partial understanding based upon my perception of the bigger picture as follows.

Traditional comments are useful to me, or anyone else reading the code, to reveal the intent of various parts of the program. Javadocs appear to be for larger projects, especially those employing a team of programmers. If my understanding is correct, the format of javadocs provides important information to other members of the team to allow them to write their code to be compatible with any other classes or methods which may interact with the code which has generated the javadoc. This provides more clean integration of the code into a fully functional program. This would be true in both development stages and upgrades. It appears that details about classes, methods, parameters, etc. can be provided without necessitating the reading of hundreds (or more) lines of code.

Is my understanding correct? What else do I need to know? How commonly are javadocs used in the professional environment? How much attention should I give to javadocs as a newbie?
 
Knute Snortum
Sheriff
Posts: 4087
112
Chrome Eclipse IDE Java Postgres Database VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
JavaDoc comments are used to document your public API. They are (are should be) used all the time by pros. Therefore you should get in the habit of writing JavaDoc comments on every method that is public or protected, and at the beginning of a class. Even just starting a comment with /** instead of /* will be a beginning. Your comments should contain only (for the most part) what the method does and not how it does it. You can use // inside the method for that. You should use an @param for every parameter, @return for what is returned, and @throws for any exceptions that are thrown. Most people agree that getters and setters need not have JavaDoc comments.

There is a lot more to commenting your code, but that's a start.
 
salvin francis
Bartender
Posts: 1612
36
Eclipse IDE Google Web Toolkit Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Will Klem wrote:
Traditional comments are useful to me, or anyone else reading the code, to reveal the intent of various parts of the program. Javadocs appear to be for larger projects, especially those employing a team of programmers. If my understanding is correct, the format of javadocs provides important information to other members of the team to allow them to write their code to be compatible with any other classes or methods which may interact with the code which has generated the javadoc. This provides more clean integration of the code into a fully functional program. This would be true in both development stages and upgrades. It appears that details about classes, methods, parameters, etc. can be provided without necessitating the reading of hundreds (or more) lines of code.


Both Java docs as well as inline (or multiline) comments help to document the code to someone else reading it.

  • Though its not a strict rule, you would mostly find comments within the structure of the program like within method codes, etc. while, javadoc typically describes the method/class or variable
  • A Javadoc follows a standard where you need to write documentation about the code as well as what are the return types, parameters, etc.
  • A Javadoc may contain html tags to format the contents
  • A Javadoc can link to another javadoc method or class
  • Tools can be used to convert your javadoc to html format so that someone can read through it and only see the docs without even reading your code. This html content ideally also has package level grouping as well as search features along side autolinking to subclasses and other implementation links


  • As a good programmer, you should maintain javadoc for all your codes specially public methods and classes. Your team size is irrelevant here, documentation sometimes even helps the one who documented it
     
    Jesper de Jong
    Java Cowboy
    Sheriff
    Posts: 16028
    87
    Android IntelliJ IDE Java Scala Spring
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    In case you didn't know yet: Javadoc is not just a special way of documenting methods, the point is that you can use the javadoc tool included with the JDK to generate HTML documentation that looks the same as the JDK API documentation.

    This is used everywhere in the Java world to generate the documentation for libraries and other software.
     
    Will Klem
    Greenhorn
    Posts: 21
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    many thanks to you three...

    My intent is to learn good habits early rather than later. After reviewing the javadoc tags, I have generated some disposable code to make sure I have used both the syntax and the intent of the comments correctly. (I am using the KeepItSimpleStupid mindset.)



    I have also generated and reviewed the javadoc pages.

    The /*...*/ comments explain the purpose of the program without reading the code for my future reference or the reference for others in my team.

    The first javadocs comment (/**...*/) lists the class by name and tells others the purpose of the class. The @author tag tells other team members who to contact if the class does not contain everything necessary for use in the program. The @see java.lang.System tag generates details about the API class used in my class.

    The second javadocs comment explains the purpose of the main method. Inherited methods are included to tell others what is supported in the method. The @param args tag details which arguments are passed to the method call. An example of how this would be useful to another team member is the type (void). The other team member needs a type (double), but my method does not pass a double; therefore, the team member must consult with me to provide him with the proper parameter type.

    The // comment explains what that line of code does.

    It looks like I need to become proficient in searching the API documentation for classes and methods to provide me with an understanding of the resources available within the API.

    Did I get everything right? What else do I need to know at my current newbie level? I am not ready yet for HTML code in my programs. That is the next topic after getting comfortable with java.
     
    Knute Snortum
    Sheriff
    Posts: 4087
    112
    Chrome Eclipse IDE Java Postgres Database VI Editor
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Great job!

    I would only change one thing: @param args The arguments passed in from the OS

    That is, right after "@param args", write a quick note about what the parameter is. Javadoc will display it something like this:

    Parameters:
    args: The arguments passed in from the OS
     
    Campbell Ritchie
    Marshal
    Posts: 55772
    163
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I always thought you wrote
    /**
     * ...
     *@param args the command-line arguments
     */

    for the main method
     
    Knute Snortum
    Sheriff
    Posts: 4087
    112
    Chrome Eclipse IDE Java Postgres Database VI Editor
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Yes, that's better.
     
    Will Klem
    Greenhorn
    Posts: 21
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    That makes sense. Thanks.
     
    Campbell Ritchie
    Marshal
    Posts: 55772
    163
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    You're welcome
     
    Will Klem
    Greenhorn
    Posts: 21
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I'd like to ask one more javadoc question before this thread closes. Suppose there are multiple classes in different .java files (only one containing a main method) under the same src. Are javadocs used to describe how they interact with each other, or is that handled via traditional comments?
     
    Campbell Ritchie
    Marshal
    Posts: 55772
    163
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Wrong question. It is more
    Does the user need to know about interactions between the different classes?
    If yes, then use /** comments */
    If no,  then use /*  comments  */

    Since you cannot put two public top‑level classes in the same .java file, then users may be unable to “see” the non‑public classes at all, in which case there is no point in telling them something they cannot use.
     
    Will Klem
    Greenhorn
    Posts: 21
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Thanks Campbell,

    Then an example may be the construction of this forum. The team of developers is responsible for different aspects of the total website. My task is to write the user name and password verification code. All that is needed in the context of my question is /** verifies username and password */. How or why the code works is moot. Methods and/or other classes performing the work are of no concern to the other developers. The only information needed is a terse comment regarding what my class does. Using /* ... */ and // for other details is reserved for those who actually have a need to examine the underlying code.

    Did I get that right?
     
    Campbell Ritchie
    Marshal
    Posts: 55772
    163
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Agree that people using the forum simply need to know the password box verifies the password. And they do not need to know how it is done. But maybe that is the difference between functionality and implementation details. You should explain enough in the documentation comments that a competent user can pick up your class and make it (or more commonly its instances) work. It is only necessary to be terse for something very simple.
  • 1:That javadoc comment is terse, because the method does something very simple not requiring much explanation.
  • 2: You can probably say that comment is unnecessary because the method title tells you everything.
  • 3: It is also slightly inaccurate
  • If you have something complicated, you will need much longer comments. Look at the Formatter class. Also look at classes like Collectors, where there are tiny tutorials embedded in the documentation comments.

    There are also things on this forum which are kept private, for example how to delete spammy posts (which we see frequently, unfortunately). You ordinary users don't need to know how to do that sort of thing, so there is no public documentation comment about that.
     
    Will Klem
    Greenhorn
    Posts: 21
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Thanks for expanding your explanation. While looking at the Formatter and Collectors classes in the API webpage, I had a light bulb turn on for me. The entries follow the same format as self generated javadocs. ... what a great guide for how to do it properly ... Read how a professional does it!

    I guess the webpage could be described as a library of API javadocs.

    Thanks again.

    EDIT:
    The light bulb was an example of Jesper de Jong's earlier post in this thread.
     
    It is sorta covered in the JavaRanch Style Guide.
    • Post Reply Bookmark Topic Watch Topic
    • New Topic
    Boost this thread!