Support annotations usage

Support annotations usage

Android support annotations help developers in writing clean and bug-free code. Using annotations in code makes finding bugs easier and helps programmers avoid legacy code issues. Basicly annotations are metadata tags which improve error finding capabilities for code inspections tools. To give an example of how useful annotations can be, let’s take a look at two approaches with and without annotations.

image alt text

Without annotations inspection tools don’t detect that method *replaceDot *will cause NullPointerException. Of course in this case it is easy to detect it yourself, but if code is more complicated such case might slip through the developer radar.

image alt text

With annotations inspection tools visibly highlight inconsistency in code. Possible error is highlighted with explanations, which prevents making a mistake. Let’s take a look at the most often used annotations.

@NonNull / @Nullable

These annotations are used for checking nullness of method parameter or method return value. If variable is marked as @Nullable it won’t be highlighted when null is passed, it will only show error whenever parameter is annotated as @NonNull and null is passed. It’s a clear information for the developer what exactly can be accepted by a method without causing any error.

image alt text

@FloatRange / @IntRange

Value constraint annotations are used whenever the method should receive values only from acceptable range, for instance setting alpha of a view which only accepts value from 0.0f to 1.0f. If the passed parameter is not within the given bound a warning is displayed.

image alt text

@StringRes / @DrawableRes / @ColorRes / @AnimRes /

Using these annotations ensures that passed resource is from the desired type. It helps prevents using wrong types inside the method like in the example below, where content description and drawable are mistakenly swapped.

image alt text

@CallSuper

Writing a method that could be overwritten, but original method should also be invoked by calling super, is a great example of a method that could use @CallSuper annotation. If you forget about invoking superclass method, an error message would be displayed.

image alt text

image alt text

@RequiresPermission

This annotation is helpful whenever the invoked method requires a permission to run successfully. For example, when the method saves a given String to a file on an external storage and WRITEEXTERNALSTORAGE permission is not specified in the manifest, the method will be highlighted.

image alt text

@IntDef / @StringDef

Whenever enum type is needed, you can use these annotations. Typedef annotations ensure that the annotated value is of the required type and they work in a similar way to enums. As shown below, it doesn’t merely check whether a given parameter has value similar to the defined type, but checks if it is of the required type. This way you are obliged to use typedef and if the value is changed or another type is specified the code will still work perfectly.

image alt text

Conclusion

Support Annotations are a great tool for maintaining and writing bug-free code. They allow to quickly pinpoint simple errors which may cause significant issues. Time spent on learning how to properly use annotations will shortly save you a lot of time while debugging. Support annotations are also a perfect complement to Guava preconditions, but that is a topic for another article.