Goldilocks and the Three Functions

How much code is enough code? Does the phrase “less is more” apply here? Some people take pride in condensing their code into “one-liners,” but the reality is that makes for obtuse, unmaintainable code where defects love to hide. Sure, there are some cases where gaining performance or some other type of efficiency justifies writing code that’s a little hard to follow, but as a general rule I avoid this kind of code whenever possible.

In the real world the true measure of the quality of someone’s code goes beyond how well it performs. High quality code must strike a balance between performance, maintainability, fault tolerance, and other factors dictated by the situation. The question remains, how much code is enough code? The answer, however unsatisfying, is: it depends.

Let’s look at some examples. We’ll be using JavaScript, for no particular reason.

Example 1

function f(n){return n<3?1:f(n-1)+f(n-2);}

Ouch, writing that hurt my soul a little bit.

This is as condensed as I could make this function, bringing everything onto a single line. The only time I would ever, ever, write code like this is if I was troubleshooting an emergency issue and needed to accomplish something immediately. Even then, if the code didn’t get thrown away at the end of the day I would go back and clean it up before saving it.

This code (which is the classic recursive Fibonacci algorithm, by the way) should never make it to a source control repository in its current state.

Example 2

Please don’t feel like you have to read all of this code. I promise, it is a working Fibonacci function.

/**
 * Calculates and returns a number, specified by a one-based index, from the
 * Fibonacci number series.
 *
 * @summary Gets a number from the Fibonacci number series.
 *
 * @author Adam Platt
 * @copyright Adam Platt 2017
 * @license MIT
 * @version 1.0.0
 *
 * @param {number} index - A one-based index specifying which element of the
 * series should be returned.
 *
 * @returns {number} the nth number of the Fibonacci series, where n is
 * the index value.
 *
 * @see {@link https://en.wikipedia.org/wiki/Fibonacci_number}
 *
 * @example
 * // returns 1
 * getFibonacciNumberByIndex_Recursive(2);
 *
 * @example
 * // returns 8
 * getFibonacciNumberByIndex_Recursive(6);
 */
function getFibonacciNumberByIndex_Recursive(index) {
    /**
     * The minimum supported index of this function. If a value below this is
     * given for the index parameter an exception will be thrown.
     *
     * @type {number}
     * @const
     */
    const MINIMUM_INDEX = 1;

    /**
     * The number of previous values to add together to get the current value.
     * This also determines the number of initial terms in the sequence with the
     * default value.
     *
     * @type {number}
     * @const
     */
    const INITIAL_TERMS = 2;

    /**
     * The default value returned when the specified index is low enough that we
     * will not make a recursive call.
     *
     * @type {number}
     * @const
     */
    const DEFAULT_VALUE = 1;

    /**
     * The error message to throw when an invalid index value is provided.
     *
     * @type {string}
     * @const
     */
    const INVALID_INDEX_MESSAGE  = 'Specified index outside the valid range.';

    /**
     * Holds the value to be returned at the end of the function.
     *
     * @type {number}
     */
    var returnValue;

    // Ensure the index provided is within the valid range.
    if (index < MINIMUM_INDEX) {
        throw INVALID_INDEX_MESSAGE;
    }

    // Check whether or not we need to make a recursive call.
    if (index <= INITIAL_TERMS) {
        // The index is low enough that we should just return the default value.
        returnValue = DEFAULT_VALUE;
    } else {
        // Because the index is high enough, we must make recursive calls to
        // determine the result.

        // Initialize the return value.
        returnValue = 0;

        // Iterate from one to (and including) the value of INITIAL_TERMS and
        // add the values of each previous number together.
        for (var iterator = 1; iterator <= INITIAL_TERMS; iterator++) {
            // Add the nth previous value to the result.
            returnValue += getFibonacciNumberByIndex_Recursive(index - iterator);
        }
    }

    // Return the calculated result.
    return returnValue;
}

I was really hoping I’d be able to push it to 100 lines or more, but I only made it to 98. For this example, I was as pedantic as possible. I invoked all the best practices I could think of such as parameter validation, avoiding in-line hard-coded numbers and strings, and giving the function a single exit point.

This level of detail, believe it or not, is not always overkill. In embedded systems where it is very expensive to patch your code once it’s been deployed, or safety critical systems where a defect could cause a loss of life, you have to write code like this. In fact, many organizations enforce coding standards to ensure all developers meet certain criteria regarding function and variable naming, exception handling, and commenting practices.

Example 3

/**
 * Gets the Fibonacci number at the specified index in the series.
 *
 * @param {number} index - The one-based index of the element to return.
 */
function fibonacci(index) {
    if (index <= 2) {
        // The first two elements of the Fibonacci series are 1.
        return 1;
    } else {
        // Every other element of the Fibonacci series is the sum of the
        // previous two elements.
        return fibonacci(index - 1) + fibonacci(index - 2);
    }
}

This is a nice middle-of-the-road function. It’s longer than one line, but still pretty short. I didn’t blindly follow all the best practices because I wrote the code while considering the context. This is not a safety critical application, it’s a programming example. We don’t need to do parameter validation. I kept some of the JSDoc comment header for the function because that’s useful for anyone using an editor that will parse it for IntelliSense. I left numbers hard-coded in-line but the surrounding comments explain their meaning. The key to this one is to make it “good enough” without sacrificing either performance or readability.

Which Approach is Just Right?

As I said above, there is no simple answer to this question, it will always depend on the specifics of the function you are writing and the context in which you are writing it. I would say, however, that the majority of cases warrant the third approach, striking a balance between concise and verbose code.

As you can see, different approaches to even a simple function can produce a vast difference in the number of lines of code produced.

Code that is properly balanced for its context is performant, easy to understand and maintain, and less likely to contain defects. Whether it makes your functions shorter or longer, it should be the only kind of code you write.

If you enjoyed this thought exercise, I would highly recommend the book Clean Code: A Handboook of Agile Software Craftmanship by Robert C. Martin.