Non-Functional Quality Delivery and Code Documentation Practices

This article discusses the delivery of non-functional quality in software development, emphasizing its importance and the challenges caused by vague requirements, weak architectural constraints, and inconsistent team practices.

Key problems include:

Non-functional requirements are often omitted from specifications.

Architecture does not enforce non-functional constraints.

Team norms rarely stress non-functional quality.

Individual developers' skills heavily influence outcomes.

Non-functional quality is hard to quantify, leading to low investment.

The article then compares several pairs of related concepts using Java as the example language, providing practical advice for each.

Comments vs Javadoc vs Self-Documenting Code

Comments are free‑form explanations for maintainers. Javadoc provides structured API documentation for both maintainers and users. Self‑documenting code relies on clear naming and structure to convey intent without external comments.

Practical suggestions:

Keep comments concise and avoid over‑commenting.

Ensure comments stay in sync with code changes.

Prefer self‑documenting code, but still provide Javadoc for public APIs.

Example Javadoc snippet:

/**
 * Gets a property from the configuration.
 *
 * @param key property to retrieve
 * @return value as object. Will return user value if exists,
 *         if not then default value if exists, otherwise null
 */
public Object getProperty(String key) {
    // first, try to get from the 'user value' store
    Object obj = this.get(key);
    if (obj == null) {
        // if there isn't a value there, get it from the defaults if we have them
        if (defaults != null) {
            obj = defaults.get(key);
        }
    }
    return obj;
}
// org.apache.commons.collections.ExtendedProperties

Exception Information vs Exception Logs

Exception information is the data carried by an exception (type, message, stack trace) used to propagate error context. Exception logs are runtime records written to aid debugging and monitoring. Both should contain sufficient business context, avoid leaking sensitive data, and be logged at appropriate levels (ERROR for exceptions, WARN for business errors).

Example exception handling snippet:

public void onApplicationEvent(ApplicationEnvironmentPreparedEvent event) {
    RelaxedPropertyResolver resolver = new RelaxedPropertyResolver(
        event.getEnvironment(), "spring.");
    if (resolver.containsProperty("mandatoryFileEncoding")) {
        String encoding = System.getProperty("file.encoding");
        String desired = resolver.getProperty("mandatoryFileEncoding");
        if (encoding != null && !desired.equalsIgnoreCase(encoding)) {
            logger.error("System property 'file.encoding' is currently '" + encoding + "'. It should be '" + desired + "'.");
            logger.error("Environment variable LANG is '" + System.getenv("LANG") + "'.");
            logger.error("Environment variable LC_ALL is '" + System.getenv("LC_ALL") + "'.");
            throw new IllegalStateException("The JVM has not been configured to use the desired default character encoding (" + desired + ").");
        }
    }
}
// org.springframework.boot.context.FileEncodingApplicationListener

Program Exception vs Business Error

Program exceptions are unexpected, unrecoverable failures (e.g., null pointer, I/O error). Business errors are expected deviations from normal business rules (e.g., invalid login). Their handling differs: exceptions should trigger real‑time alerts and be logged at ERROR, while business errors can be reported via result codes and logged at WARN.

Comparison table (excerpt):

Execution state: Exception – abnormal termination; Business error – normal branch with defined outcome.

Cause: Programming bugs, environment issues; Business rule violation.

Frequency: Low; High.

Handling: Exception protection mechanisms; Business logic handling.

Practical advice includes ensuring exceptions are logged, providing clear error messages, and separating business error handling from exception handling.

Standardization vs Specialization

Standard interfaces (e.g., JDBC) promote maintainability, portability, and global optimality. Specialization tailors implementations for performance or specific needs, achieving local optimality but reducing understandability and portability.

Guidelines:

Adopt standard practices where possible.

Avoid over‑generalization in APIs.

Isolate specialized code to limited scopes and audit regularly.

Overall, the article provides a comprehensive set of recommendations to improve non-functional quality, documentation, exception handling, and architectural decisions in Java backend development.