An issue is raised when string formatting functions that substitute placeholders with values are used as arguments to methods that already support formatting or parameterized messages natively.
In Java, this specifically refers to String.format.
Many APIs provide built-in formatting capabilities. When you wrap generic string formatting functions around these APIs, you’re adding an unnecessary layer that hurts both performance and readability.
Generic string formatting functions are typically eagerly evaluated. This means the formatted string is created immediately, even if it’s never used. This is particularly problematic in logging scenarios:
LOG.debug(format("Processing %d items", items.size())); // Always formats, even if DEBUG is disabled
When the debug level is disabled, the application still pays the cost of:
Logging frameworks provide parameterized logging that defers string construction until the message is actually needed:
LOG.debug("Processing {} items", items.size()); // Only formats if DEBUG is enabled
Each API has its own idiomatic way of formatting. Using generic string formatting makes the code less recognizable to developers familiar with these frameworks:
Using the native approach makes your intent clearer and your code more maintainable.
In Java, this specifically refers to String.format(). Common APIs with their own formatting include SLF4J (using {}
placeholders), and PrintStream and PrintWriter (with printf methods).
Using redundant manual string formatting can lead to:
In Java, this specifically refers to redundant String.format calls.
Pass the format string and its arguments directly to the API instead of pre-formatting them with String.format. How to do this depends
on the API:
{} placeholders. This
approach defers string construction until the log level is enabled. Arguments implementing java.util.Formattable are an exception:
String.format formats them with formatTo instead of toString, so replacing it with {}
placeholders could change the message.System.out/System.err): use printf instead of println with
String.format. The printf method supports the same format specifiers as String.format.PrintStream and PrintWriter both provide printf and format methods. Use
these instead of wrapping String.format in print or println.Note that println appends a line separator, so use %n at the end of the format string when switching to
printf.
In the examples below, activateUser illustrates the SLF4J case, displayResult the console output case, and
writeHeader the PrintWriter case.
import java.io.PrintWriter;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
class Example {
private static final Logger LOG = LoggerFactory.getLogger(Example.class);
void activateUser(String username, String role) {
LOG.info(String.format("Activated user '%s' with role '%s'", username, role)); // Noncompliant
}
void displayResult(int a, int b, int sum) {
System.out.println(String.format("Result: %d + %d = %d", a, b, sum)); // Noncompliant
}
void writeHeader(PrintWriter writer, String title, int pageNum) {
writer.println(String.format("Page %d: %s", pageNum, title)); // Noncompliant
}
}
import java.io.PrintWriter;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
class Example {
private static final Logger LOG = LoggerFactory.getLogger(Example.class);
void activateUser(String username, String role) {
LOG.info("Activated user '{}' with role '{}'", username, role);
}
void displayResult(int a, int b, int sum) {
System.out.printf("Result: %d + %d = %d%n", a, b, sum);
}
void writeHeader(PrintWriter writer, String title, int pageNum) {
writer.printf("Page %d: %s%n", pageNum, title);
}
}