Why isn't encoding the names of arguments in function names more common? [closed]

Question

In Clean Code the author gives an example of

assertExpectedEqualsActual(expected, actual)

vs

assertEquals(expected, actual)

with the former claimed to be more clear because it removes the need to remember where the arguments go and the potential misuse that comes from that. Yet, I've never seen an example of the former naming scheme in any code and see the latter all the time. Why don't coders adopt the former if it is, as the author asserts, clearer than the latter?

Answer 1

Because it is more to type and more to read

The simplest reason is that people like to type less, and encoding that information means more typing. When reading it, every time I have to read the whole thing even if I am familiar with what the order of the arguments should be. Even if not familiar with the order of arguments...

Many developers use IDEs

IDEs often provide a mechanism for seeing the documentation for a given method by hovering or via a keyboard shortcut. Because of this, the names of the parameters are always at hand.

Encoding the arguments introduces duplication and coupling

The names of the parameters should already document what they are. By writing the names out in the method name, we are duplicating that information in the method signature as well. We also create a coupling between the method name and the parameters. Say expected and actual are confusing to our users. Going from assertEquals(expected, actual) to assertEquals(planned, real) doesn't require changing the client code using the function. Going from assertExpectedEqualsActual(expected, actual) to assertPlannedEqualsReal(planned, real) means a breaking change to the API. Or we don't change the method name, which quickly becomes confusing.

Use types instead of ambiguous arguments

The real issue is that we have ambiguous arguments that are easily switched because they are the same type. We can instead use our type system and our compiler to enforce the correct order:

class Expected<T> {
    private T value;
    Expected(T value) { this.value = value; }
    static Expected<T> is(T value) { return new Expected<T>(value); }
}

class Actual<T> {
    private T value;
    Actual(T value) { this.value = value; }
    static Actual<T> is(T value) { return new Actual<T>(value); }
}

static assertEquals(Expected<T> expected, Actual<T> actual) { /* ... */ }

// How it is used
assertEquals(Expected.is(10), Actual.is(x));

This can then be enforced at the compiler level and guarantees that you cannot get them backwards. Approaching from a different angle, this is essentially what the Hamcrest library does for tests.

Answer 2

You ask about a long standing debate in programming. How much verbosity is good? As a general answer, developers have found that the extra verbosity naming the arguments is not worth it.

Verbosity does not always mean more clarity. Consider

copyFromSourceStreamToDestinationStreamWithoutBlocking(fileStreamFromChoosePreferredOutputDialog, heuristicallyDecidedSourceFileHandle)

versus

copy(output, source)

Both contain the same bug, but did we actually make it any easier to find that bug? As a general rule, the easiest thing to debug is when everything is maximally terse, except the few things which have the bug, and those are verbose enough to tell you what went wrong.

There's a long history of adding verbosity. For example, there's the generally-unpopular "Hungarian notation" which gave us wonderful names like lpszName. That has generally fallen by the wayside in the general programmer populace. However, adding characters to member variable names (like mName or m_Name or name_) continues to have popularity in some circles. Others dropped that entirely. I happen to work on a physics simulation codebase whose coding style documents require that any function which returns a vector must specify the vector's frame in the function call (getPositionECEF).

You might be interested in some of the languages made popular by Apple. Objective-C includes the argument names as part of the function signature (The function [atm withdrawFundsFrom: account usingPin: userProvidedPin] is written in the documentation as withdrawFundsFrom:usingPin:. That's the name of the function). Swift made a similar set of decisions, requiring you to put the argument names in the function calls (greet(person: "Bob", day: "Tuesday")).

Answer 3

The author of "Clean Code" points out a legitimate problem, but his suggested solution is rather inelegant. There are usually better ways to improve unclear method names.

He is right that assertEquals (from xUnit style unit test libraries) does not make it clear which argument is the expected and which is the actual. This have also bit me! Many unit test libraries have noted the issue and have introduced alternative syntaxes, like:

actual.Should().Be(expected);

Or similar. Which is certainly a lot clearer than assertEquals but also much better than assertExpectedEqualsActual. And it is also a lot more composable.

Answer 4

You are trying to steer your path between Scylla and Charybdis to clarity, trying to avoid useless verbosity (also known as aimless rambling) as well as excessive brevity (also known as cryptic terseness).

So, we have to look at the interface you want to evaluate, a way to do debug-assertions that two objects are equal.

1. Is there any other function it could be considering arity and name?
   No, so the name itself is clear enough.
2. Are the types of any significance?
   No, so let's ignore them. You did that already? Good.
3. Is it symmetric in its arguments?
   Nearly, on error the message puts each arguments representation into their own spot.

So, let's see whether that small difference is of any significance, and not covered by existing strong conventions.

Is the intended audience inconvenienced if the arguments are unintendedly swapped?
No, the developers also get a stack-trace and they have to scrutinize the source-code anyway to fix the bug.
Even without a full stack-trace, the assertions position resolves that question. And if even that is missing and it's not obvious from the message which is which, it at most doubles the possibilities.

Does the arguments order follow convention?
Seems to be the case. Though it seems at best a weak convention.

Thus, the difference looks quite insignificant, and the argument-order is covered by strong-enough convention that any effort to put encode it into the function-name has negative utility.

Answer 5

Often it does not add any logical clarity.

Compare "Add" to "AddFirstArgumentToSecondArgument".

If you need an overload that, say, adds three values. What would make more sense?

Another "Add" with three arguments?

or

"AddFirstAndSecondAndThirdArgument"?

The name of the method should convey its logical meaning. It should tell what it does. Telling, on a micro-level, what steps it takes does not make it easier for the reader. The names of the arguments will provide additional detail if needed. If you need more detail still, the code will be right there for you.

Answer 6

I'd like to add something else that's hinted at by other answers, but I don't think has been mentioned explicitly:

@puck says "There still is no guarantee the first mentioned argument in the function name really is the first parameter."

@cbojar says "Use types instead of ambiguous arguments"

The issue is that programming languages don't understand names: they're just treated as opaque, atomic symbols. Hence, like with code comments, there is not necessarily any correlation between what a function is named and how it actually operates.

Compare assertExpectedEqualsActual(foo, bar) with some alternatives (from this page and elsewhere), like:

# Putting the arguments in a labelled structure
assertEquals({expected: foo, actual: bar})

# Using a keyword arguments language feature
assertEquals(expected=foo, actual=bar)

# Giving the arguments different types, forcing us to wrap them
assertEquals(Expected(foo), Actual(bar))

# Breaking the symmetry and attaching the code to one of the arguments
bar.Should().Be(foo)

These all have more structure than the verbose name, which gives the language something non-opaque to look at. The definition and usage of the function also depends on this structure, so it can't get out-of-sync with what the implementation is doing (like a name or comment can).

When I encounter or forsee a problem like this, before I shout at my computer in frustration I first take a moment to ask whether it's 'fair' to blame the machine at all. In other words, was the machine given enough information to distinguish what I wanted from what I asked for?

A call like assertEqual(expected, actual) makes as much sense as assertEqual(actual, expected), so it's easy for us to get them mixed up and for the machine to plough ahead and do the wrong thing. If we used assertExpectedEqualsActual instead, it might make us less likely to make a mistake, but it gives no more information to the machine (it can't understand English, and choice of name should not affect semantics).

What makes the "structured" approaches more preferable, like keyword arguments, labelled fields, distinct types, etc. is that the extra information is also machine readable, so we can have the machine spot incorrect usages and help us do things right. The assertEqual case isn't too bad, since the only problem would be inaccurate messages. A more sinister example might be String replace(String old, String new, String content), which is easy to confuse with String replace(String content, String old, String new) which has a very different meaning. A simple remedy would be to take a pair [old, new], which would make mistakes trigger an error immediately (even without types).

Note that even with types, we may find ourselves not 'telling the machine what we want'. For example the anti-pattern called "stringly typed programming" treats all data as strings, which makes it easy to get arguments mixed up (like this case), to forget to perform some step (e.g. escaping), to accidentally break invariants (e.g. making unparseable JSON), etc.

This is also related to "boolean blindness", where we calculate a bunch of booleans (or numbers, etc.) in one part of the code, but when trying to use them in another it's not clear what they're actually representing, whether we've got them mixed up, etc. Compare this to e.g. distinct enums which have descriptive names (e.g. LOGGING_DISABLED rather than false) and which cause an error message if we get them mixed up.

Answer 7

because it removes the need to remember where the arguments go

Does it really? There still is no guarantee the first mentioned argument in the function name really is the first parameter. So better look it up (or let your IDE do that) and stay with reasonable names than blindly rely on a quite silly name.

If you read the code you should easily see what happens when the parameters are named as they should be. copy(source, destination) is much easier to understand than soemthing like copyFromTheFirstLocationToTheSecondLocation(placeA, placeB).

Why don't coders adopt the former if it is, as the author asserts, clearer than the latter?

Because there are different points of view on different styles and you can find x authors of other articles that state the opposite. You'd go insane trying to follow everything somebody writes somewhere ;-)

Answer 8

I agree that encoding parameter names into function names makes writing and using functions more intuitive.

copyFromSourceToDestination( // "...ahh yes, the source directory goes first"

It's easy to forget the ordering of arguments in functions and shell commands and many programmers rely on IDE features or function references for this reason. Having the arguments described in the name would be an eloquent solution to this dependency.

However once written, the description of the arguments becomes redunant to the next programmer who has to read the statement, since in most cases named variables will be used.

copy(sourceDir, destinationDir); // "...makes sense"

The terseness of this will win over most programmers and I personally find it easier to read.

EDIT: As @Blrfl pointed out, encoding parameters isn't that 'intuitive' after all since you need to remember the name of the function in the first place. This requires looking up function references or getting help from an IDE which will likely provide parameter ordering information anyway.