Chapter 2: Names

Good Naming

This is a very nice chapter for programming beginners. As expected I like the short sub sections. I agree with almost every point except the example in listing 2-2 (“Add Meaningful Context” on Page 28-29).

What an awful refactoring …

I do like the thereAre/Is...Letters() methods but refactoring this function into a separate class is not worth it. It adds a ridiculous amount of surface area. We gained a little descriptive code in private methods of a class that we probably won’t (or rather shouldn’t) touch again. But I’m sure we will constantly jump into it every time we try to guess what

GuessStatisticMessage message = new GuessStatisticMessage();
print(message.make(candidate, count));

actually prints (no pun intended).

The fact that this class is heavily utilizing class members for it’s state is a whole other topic.

Also the added ...Letter(s) suffix on those methods really confuses me. It seems like we are pluralizing the word “letter” even though we hand that noun ourselves as an argument. I’m sure it’s clear once you know the context but there is an opportunity to omit that context without consequence. It’s not needed in this part of the code.

Spacing aside, what makes the initial function hard to read is that the “premise” is revealed at the bottom of the function in the String.format(...) statement. You don’t know that this function is verbalizing the amount of something until the very end. Reading that line made it klick for me.

This should rather be fixed with a doc-block or small comment at the start. More importantly, the function name does not fit. This function can in fact be used to express the amount of any noun that can be pluralized with an ‘s’. If anything, all the “guess statistics” and “candidate” context should be removed. Here is my version:

Side note: I prefer curly braces on their own line for readability but I’ll keep that preference at a minimum for my examples. I also removed syntax highlighting to match the book.

/// Returns a sentence with the given amount and pluralised noun.
/// Plurilization is limited to appending an "s" to the noun!
///
/// EXAMPLE
/// Noun: "Apple", Amount: 2 => "There are 2 Apples"
private string verbalizeAmount(char noun, int amount) {
    String verb, number, pluralSuffix;
    if (amount == 0) {
        verb = 'are';
        number = 'no';
        pluralSuffix = 's';
    }
    else if (amount <= 1) {
        verb = 'is';
        number = 'one';
        pluralSuffix = '';
    }
    else {
        verb = 'are';
        number = Integer.toString(amount);
        pluralSuffix = 's';
    }
    return String.format("There %s %s %s%s", verb, number, noun, pluralSuffix);
}

And the caller:

print(verbalizeAmount(candidate, count))

I would probably be mad if someone refactored my code the way the author did. There are many more reasons why I don’t like this but I’ll probably get enough opportunities to get into that.

Please don’t refactor a trivial function into it’s own class! Especially a pure function.

Contribution

EDIT: Of course my unsupervised rants can not be left without comment! Check out my friends article (Jonas Reinhardt) about my comments for this book.