If I have a method to look for a valid email address in an array, that could either:
- Return the email address
- Return false if an email wasn't found.
- Throw an exception if an email was found, but it wasn't valid.
Should the method comment be written as though it would always work, or should it indicate that it might fail? For example:
/** * Attempts to return the email address from $data. * @param Array $data * @return Boolean * @throws My_Custom_Exception_InvalidEmailAddress */
/** * Returns the email address in the $data. * @param Array $data * @return Boolean * @throws My_Custom_Exception_InvalidEmailAddress * Throw if an email key is found in $data, but the value is empty * or if the value doesn't pass the Zend_Validate_Email check. */
Generally, I go by the rule of, if I've wrote some "throw new..." in the method, I'll write it more like the first example, because I know there's a good chance that the method won't do what the comment says, but, you can tell that by the @throws annotation, so it seems a bit unnecessary.
Is either comment style "prefered", or is it more just a case of be consistent throughout the project?