add the design.md for the calculator-conundrum

[xinri]

pull request

Add the design.md file for the calculator-conundrum for the analyzer.

Fixes: #2673

---

Reviewer Resources:

Track Policies

[kahgoh]

Thanks for wanting to contribute @xinri! My thoughts on this one:

• essential: Verify that the solution is not wrapping all the code in a try catch statement

I agree that it is worth recommending to the student not to wrap all the code in a try catch statement. However, I think this should be actionable because the objective is only to be able to use try catch (which they would've demonstrated). To me, this comment is an improvement. I think a more essential comment would be for something that doesn't meet the exercise's objective (for example, somehow solving this exercise without a try-catch.

• actionable: If the solution uses an if statement, instruct the student to use the switch case statement instead.

My understanding of this one is that we would also tell to use a switch statement if they use both an if and switch, like this one:

    public String calculate(int operand1, int operand2, String operation) {
        if (operation == null) {
            throw new IllegalArgumentException("Operation cannot be null");
        }

        if (operation.isEmpty()) {
            throw new IllegalArgumentException("Operation cannot be empty");
        }

        int result;
        switch (operation) {
            case "+" -> result = operand1 + operand2;
            case "*" -> result = operand1 * operand2;
            case "/" -> {
                try {
                    result = operand1 / operand2;
                } catch (ArithmeticException e) {
                    throw new IllegalOperationException("Division by zero is not allowed", e);
                }
            }
            default -> throw new IllegalOperationException("Operation '" + operation + "' does not exist");
        }

Did you mean something more like "If the solution does not use a switch statement, instruct the student to use a switch statement"?

• informative: If the solution does not use HashMap, instruct the student to use the operator as a key and a BiFunction implementing the calculation
  Explain that it is more efficient for performance, and it removes the cyclomatic complexity

I don't understand how or why a HashMap is needed? I thought the students would use switch as in earlier example. I'd expect a switch would be more efficient because Java can turn it into a table, but HashMap requires hashing operations and need to account for keys that hash to the same value. Using a HashMap is also not an objective of this exercise either.

• informative: If the solution does not throw the exception for Operation cannot be null and Operation cannot be empty at the beginning, instruct the student to do so
  Explain that it is better to fail fast, and it will make the code less error-prone and more readable

I generally agree with this one. The only part I'm not sure about is the readability as that can be a bit subjective.

[xinri]

Hello @kahgoh,

Thanks for wanting to contribute @xinri

It is a pleasure ;) Thanks for the comments.

Good for me, I will move the try catch comment to the actionable.

I think a more essential comment would be for something that doesn't meet the exercise's objective (for example, somehow solving this exercise without a try-catch.

For the essential, it is quite weird to mention that (no usage of try catch) because you cannot have all the unit tests passed if you don't use the try catch. So the mentee will do the code and will see that the unit test for the try catch part failed and will either search for a mentor or find on the web (most probably chatGPT).

So I will mention these blocking points in the essential but please confirm if what I said is correct.

My understanding of this one is that we would also tell to use a switch statement if they use both an if and switch, like this one:

Sorry indeed, I will put more details about the switch case. You can indeed use the if statement at the beginning. I just want to emphasize the usage of the switch case for the operation part

Did you mean something more like "If the solution does not use a switch statement, instruct the student to use a switch statement"?

correct, only for the part related to the operation.

I don't understand how or why a HashMap is needed? I thought the students would use switch as in earlier example. I'd expect a switch would be more efficient because Java can turn it into a table, but HashMap requires hashing operations and needs to account for keys that hash to the same value. Using a HashMap is also not an objective of this exercise either.

mmmh I was thinking to use this as a potential way to use lambda but it can be quite complex with the try catch, so I will forget about this.

I generally agree with this one. The only part I'm not sure about is the readability as that can be a bit subjective.

Yes, it is subjective but it is also one of the clean code notion from Martin Fowler: https://martinfowler.com/ieeeSoftware/failFast.pdf at least, it is better to inform the mentee that this clean code notion exists. After, it is up to him if he finds it interesting to apply in his code

I find it better to now execute a lot of code to find at the end that if it is null, we have to throw an exception.

[kahgoh]

For the essential, it is quite weird to mention that (no usage of try catch) because you cannot have all the unit tests passed if you don't use the try catch. So the mentee will do the code and will see that the unit test for the try catch part failed and will either search for a mentor or find on the web (most probably chatGPT).

So I will mention these blocking points in the essential but please confirm if what I said is correct.

You're right about not needing the comment if there is a test to check for this. However, it is possible to pass the tests without try catch! It can be also be solved using if and making own ArithmeticException. For example:

class CalculatorConundrum {
    public String calculate(int operand1, int operand2, String operation) {
        if (operation == null) {
            throw new IllegalArgumentException("Operation cannot be null");
        }
        if (operation.isEmpty()) {
            throw new IllegalArgumentException("Operation cannot be empty");
        }

        int result = switch (operation) {
            case "+" -> operand1 + operand2;
            case "*" -> operand1 * operand2;
            case "/" -> {
                if (operand2 == 0) {
                    throw new IllegalOperationException("Division by zero is not allowed", new ArithmeticException());
                }
                yield operand1 / operand2;
            }
            default -> throw new IllegalOperationException("Operation '" + operation + "' does not exist");
        };

        return operand1 + " " + operation + " " + operand2 + " = " + result;
    }
}

This certainly exists in the community solutions.

I think the other ones about checking if an exception is thrown if the parameter is null, empty or unknown are covered by the tests though, so I don't think those other comments are needed.

[kahgoh]

I think it might be worth mentioning where the switch case could be used. For example "... can use the switch case statement to perform the operation".

[xinri]

It can be also be solved using if and making own ArithmeticException

Indeed It is possible to do something like this ;)

For the null and empty I will remove them.

I think it might be worth mentioning where the switch case could be used. For example "... can use the switch case statement to perform the operation".

You're right. I will update the design.md with some examples.

[kahgoh]

Looks good! Thanks!

[kahgoh]

Ah, oops, there is lint failure CI:

Error: exercises/concept/calculator-conundrum/.meta/design.md:30:110 MD034/no-bare-urls Bare URL used [Context: "https://martinfowler.com/ieeeS..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md034.md
Error: Failed with exit code: 1

(see also: https://github.com/exercism/java/actions/runs/19278839635/job/55183291934?pr=3046#step:3:11)