Java code convention clarification - directly coding numerical constants

Question

In the Java Code Conventions, section 10.3 it states:

Numerical constants (literals) should not be coded directly, except for -1, 0, and 1, which can appear in a for loop as counter values.

What does it mean to 'code directly' numerical constants?

Answer 1

It refers to so called "magic numbers". Observe the following code:

float radians = 180/3.141;

versus

float degreesInRadians = myDegrees/Math.PI;

Which one is clearer?

Answer 2

It means when you use numbers in your code (other than -1, 0 and 1) that you use a constant to "label" it.

Ie instead of:

boolean pass = score >= 50;

Use this:

private static final int MINIMUM_PASS_SCORE = 50;

boolean pass = score >= MINIMUM_PASS_SCORE;

Answer 3

I believe it means to use them without defining what they actually are. For example instead of stating:

public static double PI = 3.14; //<-- Clearly defines the meaning of this value.

you're just using the decimal value.

double a = Math.pow(3.14 * r, 2); // <-- Does not define the meaning of 3.14

This makes code harder to read, and therefore is an avoided practise.