Page 1 of 1

Documentation in Java for N00blets: Focus on UML Rate Topic: ***** 1 Votes

#1 NeoTifa  Icon User is offline

  • Whorediot
  • member icon





Reputation: 2586
  • View blog
  • Posts: 15,614
  • Joined: 24-September 08

Posted 30 January 2009 - 05:31 PM

Documentation in Java for N00blets: Focus on UML by NeoTifa

Index:
Part 1: Introduction
Part 2: Comments and Comment Blocks
Part 3: Style
Part 4: Javadoc
Part 5: UML

~~~~~~~~~~~~~~~~Part 1~~~~~~~~~~~~~~~~~~~~~
Introduction:

It seems that a lot of student programmers seem to have problems documenting their code. Documentation is very important, and I'll tell you why.

Without documentation, your code is chaos! You might put down your computer, start another program, and then decide to come back to the one

program and realize that you forgot what was going on or what you were planning on doing!!! Besides, documented code is more professional. Future

programmers, collegues, clients, and bosses will not even know what is going on and get upset. If your program has a bug and you didn't document your

code, it will be a lot harder to fix it. Trust me, just document.

~~~~~~~~~~~~~~~~Part 2~~~~~~~~~~~~~~~~~~~~~
Comments and Comment Blocks:

As stated before, documentation is very important. It is also very easy. When you are doing a project on your own, you know, for fun, it doesn't really

matter how you do your style (as I will mention later), so your comments can be how you like them. If you need a simple explanation for a block of

code, then just use a simple "//". The "//" (where the ? is twice) will notify the compiler that this is a comment, and it will ignore everything else on that

line. This is called a line comment.

Example:
//This prints out "Hello, World!" to the console.
System.out.println("Hello, World!");


As you can see, in most compilers, the line comment turns grey, and will be ignored. If you are testing a line of code, and don't necessarily wish to delete

it, you can just comment it out this way when you don't wish for it to be in the program. This is extremely useful when debugging and checking the flow

of the program. You can make the program print out variables at random points to make sure the program is running the way you want, then when you

run it for real, just put a "//" in front.

//This prints out "Hello, World!" to the console.
//System.out.println("Hello, World!");


Say you want to write a bunch of lines of documentation. You can simply use the double-slash to make a block.

/////////////////////////////////////////////////
//This is a block comment
//Everything is going to be ignored
//Weeeeeeeeeeeeeeeeeeeeeeeee fun!
/////////////////////////////////////////////////

Everything in this block will be ignored by the compiler. Now for a lot of lines, you should use the javadoc form "/**" and "*/". Everything after the

"/**" will be ignored until the compiler sees a "*/". You could use this to block out whole methods, even classes, if you wanted/needed to. This is useful

for testing cases for your program.

/**
public void block() {

int block = 0;
String comment = "ignored"

}
*/


That whole method was ignored by the compiler. Make sure there are no "*/"'s before you intended, or else your code will do something funky.

~~~~~~~~~~~~~~~~Part 3~~~~~~~~~~~~~~~~~~~
Style:

I mentioned earlier that you should comment how it is easiest for you to understand. Well, sometimes thats not always the case, but I will explain that in

the next section. Everyone codes differently, and everyone documents differently. I believe a coder's programming/documentation style is unique to

them, and is a signature of sorts. I, when working on personal projects, prefer to block my code up, mainly my variables.

Example:
/////////////////////////////////////

//Imports

import java.util.*;
import java.io*;
import java.swing.*;
import java.applet.*;
import java.awt.*;

/////////////////////////////////////
public class main(String[], args) {

public void main(){

//////////////////////////////////////

//Main method variables

int one = 1;
int two = 2;

File file = new File("file.txt");
Scanner fScanner = new Scanner(file);

////////////////////////////////////////

//Code goes here...

}//End main method

}//End main class


It is also good style to add line comments to the end of your brackets ("{}") so you do not mix them up. This is just how I do things, so feel free with

creating your own style.

~~~~~~~~~~~~~Part 4~~~~~~~~~~~~~~~~
Javadoc:

When you are out in the professional world, every company will have you do things different, but one thing will not change: they will have you document

universally. Javadoc documentation is the style of documentation that every programmer knows how to read. It doesn't matter who wrote it, and what

personal style they use, the program will be documented the same way. This is to ensure that everyone can read the code and understand what you're

trying to do, what your parameters are, what your return values are, and the purpose of the the block of code you are documenting.

Tags:

Sometimes in peoples code you see "@" signs. These are supposed to be in the javadoc documentation. This is a code to the javadoc that this is a value

of some sorts. Here are the three most basic ones:

@author Designates the authors name
@param Designates the parameters of the function/methode being documented
@return Designates the return value

You can make any kind of tag you want. I use @date a lot to show when I made it or updated it. Heck, you can even make a @update. I, on occasion

on my personal projects, make a @sexiness tag to rate the sexiness of my program (scale of 1 to 10). ^____^

Pre- and Post- Conditions:

It's nice to put in conditions to the methods when documented. Say, for example, you have a parameter that is a String, and you want it to have 9

characters in it, just say so in the Pre-Condition. In the Post-Condition you should put what the expected behavior of the method/function should be.

Putting it all together:

Javadoc comments should be in the "/**" and "*/" tags.

/**

Decribes the method

@param 
@return  

Pre-Conditions:  
Post-Conditions: 

*/

public int method() {

return variable;

}


A better (not perfect) example is a class made for my lab (that I have still yet to finish and turn it :P)

package cs241lab2;

/**
 *
 * @author Erica Boyer
 * @date 1-24-09
 * 
 */



public class UsedCars {

    /**
    * 
    * @enum PaintColor Holds the different colors of the car
    * @param make Holds the make of the car (ex. Buick, Porche, etc.)
    * @param vinNum Holds the vin number of the car (9 digits and letters)
    * @param year Holds the year of the car
    * @param color Holds the color of the car
    * @param rating Holds the cars rating (0.0 to 100.0)
    * 
    */
    
    public enum PaintColor {BLACK, WHITE, BLUE, RED, GREEN, OTHER}
    
    private String make;
    private String vinNum;
    private int year;
    private int mileage;
    private PaintColor color;
    private double rating;
    
    /**
     * 
     * No-arg Constructor UsedCars
     * 
     */
    
    public UsedCars() {
        
        make = "";
        vinNum = "0000ABCD0";
        year = 0000;
        mileage = 0;
        color = PaintColor.OTHER;
        rating = 0.0;
        
    }//End UsedCars no-arg constructor
    
    /**
     * 
     * Constructor UsedCars
     * 
     * @param m Sets make to m
     * @param v Sets vinNum to v
     * @param y Sets year to y
     * @param mile Sets mileage to mile
     * @param c Sets color to c
     * @param r Sets rating to r
     * 
     */
    
    public UsedCars(String m, String v, int y, int mile, PaintColor c, double r) {
        
        make = m;
        vinNum = v;
        year = y;
        mileage = mile;
        color = c;
        rating = r;
        
    }//End UsedCars constructor
            
    /**
     * 
     * The setMake method sets the make of the car to the user's arg m
     * 
     * Pre-condition: make has to be a legitamate String of a company
     * Post-condition: make will be what user has defined
     * 
     * @param m Sets make to m
     * 
     */
    public void setMake(String m) {
        
        make = m;
        
    }//End setMake method
   
    /**
     * 
     * The setVinNum method sets the vin numer of the car to the user's arg v
     * 
     * Pre-conditions: Has to be a String with 9 numbers and letters
     * Post-conditions: vinNum will hold the cars vin number
     * 
     * @param v Sets vinNum to v
     * 
     */
    
    public void setVinNum(String v) {
        
        vinNum = v;
        
    }//End setVinNum method
    
    /**
     * 
     * The setYear method sets the year of the car
     * 
     * Pre-condition: Has to be a 4 digit number
     * Post-condition: vinNum will hold the year
     * 
     * @param y Sets year to y
     * 
     */
    
    public void setYear(int y) {
        
        year = y;
        
    }//End setYear method
    
}//End UsedCars class



The cool thing about javadoc is if you run it through the console (type in javadoc main.txt methinks), the console will create a bunch of HTML or HTM

files in the directory where you loaded it from. You click the one that says index.htm and it will load and show you your classes/methods involved just

like in the API!!!! See, anyone can add on to java ^____^.

~~~~~~~~~~~~~~~Part 5~~~~~~~~~~~~~~~~~~~~
UML:

Every professor is at some point going to ask for a UML diagram of your program, so it is handy to know what exactly that is. A UML diagram, or

Universal Modeling Language diagram, is a graphic or pictoral view of your program. You use this to draft your future program. With just the UML, you

can make a basic "stub" program that compiles. This is standardized as well, and has its own set of symbols. To make a UML, you can do it in

MSPaint, on paper, or a UML-making program (for you fancy-pants).

First, make a box.
Next, divide it into three parts.
In the top box you write the class' name
In the second box you write the variables in that class
In the last box you write all of the methods in the class.

Pretty simple, huh? Now lets take a closer look.

Top box:

Seriously, all it is is the class's name.

Middle Box:

This holds the attributes of the class. It follows the formula:

(+/-/#)attribute: type = initialization

The attribute is the variable name of which you decide. The type is what type of variable it is (int, String, double, etc). If you plan to initialize your

variables, you put an equals sign ("=") and the value it will hold. Now, as for the (+/-/#), this is for the availability of the variable.

+ means the variable/method is public
- means the variable/method is private
# means the variable/method is protected.

You always put the sign before the variable name.

Last Box:

This holds all of the methods and constructors you plan on making (contructors are first, methods next). These follow the formula:

(+/-/#)operation(arg list): return

The (+/-/#) you already knows shows whether it is public/private/protected. Operation is the constructors/methods name. The arg list in the parenthesis

shows values taken into the method (int w, String s, double x), and return is the return variable.

And example is this diagram I found on Google:

Posted Image

or this one http://www.ukoln.ac....study-03/qa-uml

The lines show the relationships and inheritance between the classes. (The "has a" relationships the classes have) Wikipedia has a good diagram

showings inheritance. http://en.wikipedia....i/Class_diagram Usually a class will point to a class it derived from or extended from (child

points to parent).

As for Enumerated types, there has been a lot of debate on this, but according to my professor, since enums are considered a seperate class, to have a

sperate box pointing to the class that is using it.

Well, that's it for now. Stay tuned for the next epic tutorial by yours truely.

Is This A Good Question/Topic? 3
  • +

Replies To: Documentation in Java for N00blets: Focus on UML

#2 ayman_mastermind  Icon User is offline

  • human.setType("geek");
  • member icon

Reputation: 126
  • View blog
  • Posts: 1,860
  • Joined: 12-December 08

Posted 06 February 2009 - 01:47 PM

Thanks very much for making the tutorial, very useful, especially for beginners i liked the UML part the most, grats for your first tutrial, keep up the good work ;)
Was This Post Helpful? 0
  • +
  • -

#3 KYA  Icon User is offline

  • g++ jameson.cpp -o beverage
  • member icon

Reputation: 3093
  • View blog
  • Posts: 19,139
  • Joined: 14-September 07

Posted 06 February 2009 - 01:58 PM

An enum should have its own separate box in a UML diagram.
Was This Post Helpful? 0
  • +
  • -

#4 NeoTifa  Icon User is offline

  • Whorediot
  • member icon





Reputation: 2586
  • View blog
  • Posts: 15,614
  • Joined: 24-September 08

Posted 07 February 2009 - 04:41 PM

View PostKYA, on 6 Feb, 2009 - 12:58 PM, said:

An enum should have its own separate box in a UML diagram.


Didn't I put that in there?
Was This Post Helpful? 0
  • +
  • -

#5 thepeoplescoder  Icon User is offline

  • D.I.C Head
  • member icon

Reputation: 17
  • View blog
  • Posts: 97
  • Joined: 02-February 09

Posted 07 February 2009 - 05:16 PM

A thorough introduction. Good job. xD
Was This Post Helpful? 0
  • +
  • -

#6 NeoTifa  Icon User is offline

  • Whorediot
  • member icon





Reputation: 2586
  • View blog
  • Posts: 15,614
  • Joined: 24-September 08

Posted 07 February 2009 - 05:20 PM

Thank you, thank you *takes a bow*. See, you all underestimated me! I do stuff.... other than spam XD
Was This Post Helpful? 0
  • +
  • -

#7 KYA  Icon User is offline

  • g++ jameson.cpp -o beverage
  • member icon

Reputation: 3093
  • View blog
  • Posts: 19,139
  • Joined: 14-September 07

Posted 10 February 2009 - 12:31 PM

Weird, I thought I read a comment asking about enums? I must be going crazy.
Was This Post Helpful? 0
  • +
  • -

#8 spikesanguine  Icon User is offline

  • New D.I.C Head

Reputation: 1
  • View blog
  • Posts: 16
  • Joined: 10-October 08

Posted 05 April 2009 - 06:07 PM

Really great explanations of UML.
Was This Post Helpful? 0
  • +
  • -

#9 crummydo  Icon User is offline

  • D.I.C Head

Reputation: 6
  • View blog
  • Posts: 223
  • Joined: 06-January 09

Posted 11 August 2009 - 07:32 PM

For Ubuntu users, go to the repository and search for UML. There are a couple of good programs you can use for designing UML. Also, Netbeans (any platform) has a UML plugin that is awesome. It will even build Java code for you in a very basic skeleton based on your diagrams, or even reverse engineer a UML from a Java program. Cool.
Was This Post Helpful? 0
  • +
  • -

#10 k3y  Icon User is offline

  • D.I.C Head

Reputation: 36
  • View blog
  • Posts: 205
  • Joined: 25-February 12

Posted 02 March 2013 - 08:17 PM

Great tutorial, I am going to start commenting my code.
Was This Post Helpful? 1
  • +
  • -

Page 1 of 1