custom annotation naming

Custom annotations in Java should be named to describe what’s required of the method, and not which functionality we would like applied.

For example;

@RequiresRole(role = ADMIN)

Instead of;

@CheckRole(role = ADMIN)

If we start naming our annotations after “how” they work, and not “what” we want, we go down a route of also describing the edge and error cases. It’s very easy for a @CheckXYZ annotation to start accepting parameters that control; how the exception is thrown, which type of exception, etc.

There’s precedent for describing the requirements of the method, rather than “how” to implement the requirements, for example;

  • @NotNull instead of @CheckNotNull
  • @PostMapping instead of @HandlePostRequest
  • @ExceptionHandler instead of @HandleException

Name custom annotations based on their requirements, not their implementation.