A guard clause is the check whether a precondition is met when calling a function. When a function is called, a guard clause checks whether a necessary function value was initialized at all, and whether it has a permissible value. If so, nothing happens. If not, it forms an understandable, readable error message.
If errors occur at some point during the program run, if an incorrect value would lead to an uncontrolled program state, the error messages are usually incomprehensible because the context is missing. Or, incorrect data is not even noticed and later leads to completely different problems, the cause of which is unclear. In programmer terms, a guard clause is the same as an assert statement, with the difference that assertions are only evaluated if this was parametrized when the JVM started. A guard clause is always evaluated. Its check is very lightweight and has no negative impact on today's computers' performance.
ArrayIndexOutOfBoundsException: 12
→ 'monthElement' out of range: 12 not in [0..11]
NoSuchElementException: -2.99792458E8
→ 'value' out of range: -2.99792458E8 not > 0
IllegalArgumentException: Incompatible types.
→ org.apache.activemq.artemis.jms.client.ActiveMQTextMessage 'arg' is not a (subclass of) javax.jms.MapMessage
For a more detailed explanation of what guard clauses are, see this article (in German).
Related Issues
5756
Expected Benefits of this Development
The implementation of guard clauses improves the error messages for invalid inputs and makes system operation and troubleshooting easier. It documents the value ranges of function calls in an easy-to-read form, improving the understandability of the source code for other programmers, unlike when an assumption is known to a programmer, but not documented. For the programmer, this reads like someone reads instructions for filling out a form. This mainly affects unfavorable data via SRU, damaged or incorrect files, or typos in configuration files. It also finds programming errors earlier.
Estimated Costs and Complexity
low ~ less than 5 working days.
A draft has already been made available in the pull request linked above. The aim of this development is to review other places in the source code, where parameters are checked or exceptions are thrown, or where value ranges for parameters are documented in the Javadoc, and to standardize them.
solth
commented
7 months ago
Description
A guard clause is the check whether a precondition is met when calling a function. When a function is called, a guard clause checks whether a necessary function value was initialized at all, and whether it has a permissible value. If so, nothing happens. If not, it forms an understandable, readable error message.
If errors occur at some point during the program run, if an incorrect value would lead to an uncontrolled program state, the error messages are usually incomprehensible because the context is missing. Or, incorrect data is not even noticed and later leads to completely different problems, the cause of which is unclear. In programmer terms, a guard clause is the same as an
assertstatement, with the difference that assertions are only evaluated if this was parametrized when the JVM started. A guard clause is always evaluated. Its check is very lightweight and has no negative impact on today's computers' performance.Examples:
Examples for improving error messages:
For a more detailed explanation of what guard clauses are, see this article (in German).
Related Issues
5756
Expected Benefits of this Development
The implementation of guard clauses improves the error messages for invalid inputs and makes system operation and troubleshooting easier. It documents the value ranges of function calls in an easy-to-read form, improving the understandability of the source code for other programmers, unlike when an assumption is known to a programmer, but not documented. For the programmer, this reads like someone reads instructions for filling out a form. This mainly affects unfavorable data via SRU, damaged or incorrect files, or typos in configuration files. It also finds programming errors earlier.
Estimated Costs and Complexity
low ~ less than 5 working days.
A draft has already been made available in the pull request linked above. The aim of this development is to review other places in the source code, where parameters are checked or exceptions are thrown, or where value ranges for parameters are documented in the Javadoc, and to standardize them.