Question

I want to write clean code. So When writing a method I want to inform the caller of a method about parameters, return type, exceptions, etc. When calling a method the caller should already know if the method can return null or if a parameter can be null.

I can explain this in the javadoc but I want to do it with annotations. I know jetbrains and now JSR305 trying to solve this issue but I think they are not enough.

So:

1. Is there any large annotation library for parameters and return types

2. Is this annotation only for only readability of code, or does it throw an exception if an unexpected value/outcome is encountered at run time?

3. Method declarations should include only base checked exception or subclasses of it too like

   public void foo() throws ConnectionException, AuthenticationException {
   }
   
   public class AuthenticationException extends ConnectionException {
   }
   

Answer 1

This might or might not be what you have in mind – design-by-contract annotations allow you to specify that the parameters and return type of a method must meet certain conditions to be considered correct. Take a look at cofoja:

Contracts for Java enables you to annotate your code with contracts in the form of preconditions, postconditions and invariants.

These contract annotations are

• easy to write and read,
• and checked at runtime.

Annotating code with contracts helps you:

• design,
• document,
• test, and
• debug

your programs.