Consider the unfortunate future developer who needs to understand your code quickly. Will they curse you or thank you? Where a method is being called with a special hard-coded value like 5930, it is sometimes appropriate to leave a comment or code hint about the value being passed in, avoiding a need to drill down into the body of the method to check what kind of parameter it is.
These values are called “Magic Numbers” or “Magic Strings” and are not recommended. Automated code quality tools such as Checkstyle will find many of these future maintenance problems for you.
In the following example, it is not immediately clear (at least without special mouse hovering) what the last three parameters are used for.
// Create the binary invoice file
return this.getInvoiceHelper().generateInvoice(
customerId,
clientId,
username,
true,
false,
5930);
Most good integrated development environments offer a mouseover effect that will show the method signature, but Javadoc is not always hooked in and where there is a large list of parameters (e.g. 20), the popup can be unpleasant. The following small adjustment is not strictly necessary but is instantly clearer.
:
public static final int DEFAULT_ISO_COMPLIANCE_CERTIFICATE_NUMBER = 5930;
:
// Create the binary invoice file
boolean includeHeadings = true;
boolean printPreview = false;
return this.getInvoiceHelper().generateInvoice(
customerId,
clientId,
username,
includeHeadings,
printPreview,
ISO_COMPLIANCE_NUMBER);
Alternatively comments are also useful* for extra clarity.
// Create the binary invoice file
return this.getInvoiceHelper().generateInvoice(
customerId,
clientId,
username,
true, // include headings?
false, // print preview?
DEFAULT_ISO_COMPLIANCE_CERTIFICATE_NUMBER);
*Be selective where you use this kind of hint in the code. Automatic refactoring of method signatures and variable names can make the comments invalid.
