Result considered harmless

[blackk-foxx]

In a couple of recent code reviews, reviewers have flagged my choice of "result" as a variable name as a violation of clean code principles. As a clean code advocate and practitioner, I understand the reasoning behind this critique. We want names that are clear and unambiguous, and a name like "result" is certainly vague. But I want to make the case for using the name "result" for a specific purpose -- as the return value of a function.

Consider a Python power function that computes n raised to the e power:

def power(n: int, e: int) -> int:
    result = 1
    for _ in range(e):
        result *= n
    return result`

The name of the function already conveys what it does, and what its return value is expected to be. What additional information could be conveyed by naming the variable something other than "result?" Maybe "power_value" or "power_result?" I claim that such names actually introduce ambiguity. Since the name of the "power" function already indicates that it returns a power, what would "power_value" or "power_result" mean? Something slightly different?

In contrast, if we accept the name "result" to represent the return value of a function, then there is no ambiguity.

In fact, the Nim language treats "result" as a special name that allows an implied return value:

proc power(n: int, e: int): int =
    result = 1
    for _ in range(e):
        result *= n
    # Returns result

Anyway, this situation should be rare. Ideally, we would try to avoid reliance on mutable variables and follow functional paradigms wherever possible:

from functools import reduce
def power(n: int, e: int) -> int:
    return reduce(lambda acc, _: acc * n, range(e), 1)

But in the rare cases where we need a mutable variable to calculate the return value, I claim that the name "result" is not only acceptable but preferable.

Other thoughts?

[megabyde]

It makes sense for situation like in your example. Here are some situations where it could decrease readability:

• Large functions
  If the function is long or has multiple conceptual steps, result might be confusing:

  def process_order(order: Order) -> ProcessResult:
      result = ProcessResult()
      # 80 lines of logic
      # multiple conditionals and side effects
      # more mutation of 'result'
      return result

  Here, result carries a lot of evolving invariants. Because the function is doing more than "compute and return a simple value," the name should reflect what phase or invariant the object currently has.

• Multiple “results”
  If the function returns something that competes mentally with other important values:

  def solve_quadratic(a, b, c):
      discriminant = b*b - 4*a*c
      # ...
      result = (x1, x2)
      return result

  roots is likely better than result here.

We can argue that within a small function body, result is a standard idiom meaning "the return value I’m constructing." Similar idioms already exist:

• i, j as loop indices;
• acc or accumulator in folds;
• tmp for a short-lived temporary.

[blackk-foxx]

I agree with both of your counter-examples. Regarding the first one, I would go further to say that we should always strive to use immutable intermediate objects wherever possible/practical when we need to do multi-stage processing. Anyway, Uncle Bob would also likely advise us to keep extracting until the complexity in our top-level function is well under control.

[rhyolyn]

In the context of your short power function, result is very readable. Technically, you could have used power instead of result, but that would shadow the outer scope and hopefully spark genuine outrage in your reviewers. Using the clean code convention of short (potentially even one character) variable names for very short scopes, you could use pow or p. I rather like p, because it would make the function even tinier, but I don't object to result here. Would using p make it less readable? I expect the answer depends entirely on the reader.

It would be amazing if we could squeeze every solution into a tidy Clean Code box, but I haven't figured out how to do that yet. I do love how these little dilemmas encourage discussion.

[blackk-foxx]

My initial reaction to your recommendation to use power instead of result was that it is not possible, as most languages will not allow you to define a variable with the same name as a function in the same scope. But something in the vague recesses of my memory was telling me that there are/were some languages that actually require it. Sure enough, the Retro Computing site helped me to recall that the Pascal, FORTRAN, and BASIC languages all require that kind of syntax -- see https://retrocomputing.stackexchange.com/questions/17686/in-what-languages-is-the-return-value-set-by-assigning-to-the-function-s-name.