Java Tutorial – Organizing your Code

Java Tutorial – Organising Java Projects

As your programs grow in size and complexity, organisation and documentation will become more important. Applications developed in Java must be well-constructed and documented in order to function within the Object Oriented design model. Under this model, applications comprise a set of components interacting with one another – for this to be possible, the elements within must be clearly defined and explained. Even when you develop your own smaller projects, you will find that spending a little time and thought on these choices will save you a lot of headaches in the long run.

There are a series of simple measures that can contribute to a well-organised project, for example, the simple act of using plenty of whitespace and indentation in your code instantly makes it more readable, while this sounds boring and very uneventful .

Dividing up Requirements

It can be tempting, when starting a project, to sit down and immediately produce code, but resisting this urge can make life a lot easier. Once you have a set of requirements for your application, it can be extremely helpful to work out a ‘high-level’ plan before you start to write any code. For example: split the requirements into related sections, then use these to decide what your packages and classes will be. Even if you find that your implementation causes you to alter this initial plan, it provides a much more coherent starting point.

There are various modelling tools that can help this process, such as UML (Unified Modelling Language) – however, even if you decide not to choose such a formal approach, the simple act of splitting the requirements into groups can help you to visualise how you are going to solve the problems at hand.

Java Naming Conventions

It is well worth spending a few moments during coding to decide on appropriate names for variables, methods, classes and packages. In addition to the fact that this makes your work much more amenable to being used in other applications, it also makes your own development process easier. When you look back at a piece of code that you wrote some time before but have forgotten the details of, meaningful variable and method names will help you to understand it far quicker than if you have to read and process each line of code in your head! Although it may seem cumbersome at times, using whole words in your names can make your code much more readable.

For the same reason, observing the standard naming conventions for the language is always a good idea. In Java, this includes the following:

• variables should start lowercase, with uppercase letters indicating words within, e.g. myNumber, costPerPortion.
• method names should indicate (normally using verbs) what the method does, e.g. getCost, displayNames.
  • methods used to get and set values should use the conventions getValue (e.g. getCost) and setValue (e.g. setCost) respectively.

Comments and Documents

Regardless of whether you are working on your own or as part of a team, the inclusion of informative comments in your code will always help the development along. The Java language features a variety of different types of comment:

Single line comments are used for short pieces of information throughout your code:

	//print each name in the array
for(int i=0; i

Multiline comments are used for more lengthy explanations, particularly if your code features a complex algorithm:

	/*  This algorithm does the following:
		-first it does this
		-then it does this
		-and so on
	*/
for(int i=0; i

Javadoc

Java has its own system of documentation that is effectively built-in to the language. You can use Javadoc to automatically generate html documentation for your projects, and all you need to do is include Javadoc comments in your code:

/**
Method calculates total cost from individual cost
... more explanation ...
@param someNumber -int value representing individual cost
@return totalCost -int value representing total cost 
*/
public int getTotalCost(int someNumber)
{
	//method code calculations..

	return totalCost;	
}

Javadoc generates html based on such comments, which contain special tags such as @param and @return – if you include these the Javadoc will display this information in a standardised way. You should include Javadoc comments immediately before Class declarations, instance variable declarations, methods and constructors. The Java API is an example of Javadoc that you can view.

Advertisement