Inconsistencies in @throws tags can increase costs
1 – that a @throws tag exists for a function that throws exceptions.
2 – the number of @throw tags and the number of throw tokens matches.
3 – the exception type.
Search all @throw tags in the documental comment of a function.
Search all throw instruction in the function code.
Checks that all exceptions thrown in the code whose type is known have a corresponding @throw tag. Once this check is done, those tags are removed from the list. Remaining tags are related to throw instructions on unknow type exception.
For this remaining list of tags, check that there is at least one tag if it exists at least one throw instruction on an unknow type exception, and that there is not more tags than such throw instruction.
throw new PHP_Exception1(‘Error’); throws a exception whose type is “PHP_Exception1”
throw $this->callSomeFunction(); throws a exception whose type is unknown (due to analyzer limitation).
Why you should care
Every function that throw exceptions must have a throw tag. Try to reduce the number of function that throws exceptions without having a @throws tag.
It is recommended to avoid these in order to ensure the code is more readable and cost effective.
About CAST and Highlight’s Code Insights
Over the last 25 years, CAST has leveraged unique knowledge on software quality measurement by analyzing thousands of applications and billions of lines of code. Based on this experience and community standards on programming best practices, Highlight implements hundreds of code insights across 15+ technologies to calculate health factors of a software.