Learn Programming With Java

Defining a good quality function

How do you write quality functions? It requires both designing your code components effectively and clearly identifying elements.

What is a function to begin with? Here are a few guidelines to follow:

First, if two or more lines of code repeat more than one time, it should be a function. Check out the example below:

// feeding a person
System.out.println("Break 2 eggs on a pan"); 
System.out.println("Add chopped vegetables"); 
System.out.println("Stir occasionally for 2 mins");

// feeding another person
System.out.println("Break 2 eggs on a pan"); 
System.out.println("Add chopped vegetables"); 
System.out.println("Stir occasionally for 2 mins");

// OR
// define a function
public void makeOmelet() {
System.out.println("Break 2 eggs on a pan"); 
System.out.println("Add chopped vegetables"); 
System.out.println("Stir occasionally for 2 mins");
}

// feeding a person
makeOmelet()

// feeding another person
makeOmelet()

Second, if the code becomes lengthy and hard to navigate, it’s best to put it into a function even if it only needs to be executed once. If the content of your function doesn't fit on your development screen, and you can’t follow the logic of it at a glance, it's likely too long. Fifty lines could be a good arbitrary reference point:

// A long chunk of code - 50+ lines 

// replace with functions
public void performTheBeginning() {
// 50 or less lines of code
}

public void performTheEnding() {
// 50 or less lines of code
}

performTheBeginning();
performTheEnding();

Finally, if you have a function that completes more than one task, you should split it up into smaller functions. From there, make another global function that calls those smaller functions. For example, you need a payment transaction to do two things: save the transaction, and notify the system to perform the related updates:

public void processPayment() {
// save transaction
// notify the system
}

// instead, split in sub-functions
public void saveTransaction() { 
}

public void notifySystem() { 
}

// and call them both
public void processPayment() { 
saveTransaction();
notifySystem();
}

Here is another classification of functions: purposed-based:

1. Interface(behavior)functions - these interact with external elements. An example would be the payment processing function. 

2. Helper functions - these are created for internal convenience and readability. Those would be sub-functions created for convenience within the payment processing function.

Let's look at another example. Using car objects as an example, the interface functions are the behaviors a class needs to implement to be used outside, such as:

• drive

• turn

• start

• stop

The helper functions could be:

• calculateSpeed

• startEngine

• stopEngine

The interface functions must be sufficient to use an object to its expected capacity. The helper functions need not be visible to the external code and should be clearly architected within the class.

Formatting the code

Formatting plays a significant role in defining the quality of your code and can be separated into the following components:

• Naming

• Commenting

• Writing style

Each is important and needs to be used wisely.

Naming

Naming is one of the essential components of good quality code and consists of two parts:

• Coming up with a name

• Following naming conventions

Coming up with a name is not a trivial task. The name you use must reflect the purpose of your function. Its name must say what it does.

For example, if a you have a car object, and it's drivable, perhaps you'd have a function called drive. As an alternative, you could name it move, but it's not as clear. You could also use makeCarMove.

In another example of a class that would generate geometrical shapes, you could have shape- making functions, which you could call makeSquare or makeRectangle. As you can see, using the prefix make in this example is more appropriate than in the previous one.

The same concept applies to naming parameters of a function. Just like any other variable, a parameter's name should reflect its purpose:

public void paint(Car car, String color) { // Encouraged
}

public void paint(Car c, String clr) { // Discouraged
}

Additionally, it's important to follow naming conventions. Those depend on the programming language and your development team.

In Java, the camel case naming convention is used. As you may recall from a previous chapter, the first word in function and variable names start with a lowercase letter. The first word in the names of named types (such as classes) starts with an uppercase letter.

public void createShape() { // Correct
}

public void CreateShape() { // Incorrect
}

Commenting

Comments need to explain what is not understood by reading the code. It could also include some extra tips. The most common examples are:

• Why - explaining why a certain implementation approach was chosen over another. Especially if another appears to be a stronger choice.

• Tips - extra tips include things such as available options within the class functionality being used from outside.

There are two types of comments:

• Single line

• Multi-line

Single line comments are defined by using a double forward slash // at the beginning of the comment. The rest of the line is considered a comment:

// single line comment

Those are used for short notes. If the line is wrapping on a typical developer environment screen, consider multi-line comments. Using multiple single line comments is appropriate for short comments if they are contextually different. Alternatively, a single multi-line comment is more appropriate.

Multi-line comments are defined by using opening and closing combination of characters/* and*/respectively:

/* first line of multi-line comment 
second line of multi-line comment 
*/

Writing style

Writing style refers to how you arrange the components of your code.

There are few common battles that have no right or wrong answers:

• Using spaces - here're a few examples:

int a = 10;
a = a * 21;
// comment

versus:

int a=10
a=a*21;
//comment

• Same line or new line braces:

if (true) {
}
else {
}

versus:

if (true) 
{
}
else 
{ 
}

• Tabs vs. spaces to format intent within the files.

Both variations of each group are acceptable and depend on your team. A mix of different variations here and there is a big no-no. The team should have a unique writing style everyone follows. However, you will frequently be fixing and improving the existing code. In this case, it's best to follow the existing style used by previous. contributors.

Summary

In this chapter, we've covered basic aspects of writing good quality functions:

• Rules to follow when deciding what should be a function:

  • When two or more lines of code need to be executed more than once

  • When a chunk of code is too large to grasp and doesn't fit on a screen

  • When a function completes multiple tasks, use assisting sub-functions

• Functions are classified into two categories: 

  • Interface functions - those that provide the class functionality outside of the class

  • Helper functions - convenience functions that are used within the class and improve architecture and readability

• Formatting is an important component of the good quality code. It includes:

  • Following naming conventions

  • Commenting

  • Using a consistent writing style