Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll

Java Annotations

Preview

Start a free Courses trial
to watch this video

Sign up for Treehouse

Project Overview: Docgen

3:48 with Chris Ramacciotti

You've heard about the importance of documenting your code. During this video I'll introduce the motivation behind writing our own annotation: the ability to scan for full documentation of non-private methods.

Unit Test Annotation Example

A typical example illustrating the simple power of custom annotations is using them to code and control the execution of unit tests. The tutorial linked below also illustrates an additional component of reflection that I don't cover in this course: method invocation. In this course I focus on using reflection to inspect a Java class. One can also use reflection to actually interact with it, and in this case invoke (or call) methods that have been annotated with @Test:

Clean Code, by Robert C. Martin

In this video, I reference the following quote:

There is nothing quite so helpful and satisfying as a well-described public API.

- Robert C. Martin

This quote is taken from the book Clean Code, which is a wonderful guide on code readability. In this book, among other topics Martin discusses what he considers to be best practices in naming conventions, error handling, and how to practice good test-driven development. Read more about it on Amazon:

Java Style Guide

Speaking of clean code, a good practice as you start or continue your code-writing career is to adopt standards & conventions for your Java code. Also known as a "style guide", this helps you and your team maximize code readability, keeps your team's codebase consistent, and allows you to develop a baseline of expectations for any developer that joins your team. The best style guide for your team is the one you adopt. Don't have one? Here is one from a company you may have heard of:

Related Discussions

Have questions about this video? Start a discussion with the community and Treehouse staff.

Sign up

    Related Discussions

    Have questions about this video? Start a discussion with the community and Treehouse staff.

    Sign up

    [MUSIC] 0:00
    [SOUND] Welcome back to annotations and Java. 0:04
    So you've seen the most basic use of annotations with those that are built in, 0:07
    override, deprecated, and suppressed warnings. 0:11
    In addition, I mentioned a couple of examples of how you can leverage a third 0:16
    party library with a quick edition of well placed annotations. 0:20
    But, what if there isn't a third party library out there that suits your needs? 0:25
    Or, what if your available options are all overkill for a small lightweight project? 0:30
    Well, I guess you better write your own annotation. 0:35
    We could go through any number of examples here, 0:39
    such as the classic example of annotations in unit tests. 0:42
    This would be a useful exercise. 0:46
    And by all means you should check one out. 0:48
    I put a link to one in the teacher's notes. 0:50
    What I'd like to do, is consider here, the process of documentation. 0:52
    Specifically on the development of a public API. 0:56
    I agree with Robert Martin, who in his book Clean Code, says that there is 1:01
    nothing quite so helpful and satisfying as a well described public API. 1:05
    In other words, you should document your exposed or public methods. 1:11
    What I'm going to do, is demonstrate the writing of an annotation that will allow 1:15
    us to analyze our code and check for any undocumented public methods. 1:19
    When we're all done, you'll have a complete working example 1:24
    of a custom annotation that you can use as a model for future projects. 1:28
    The new workspaces project that you see, 1:33
    is an application that's meant to provide an alternative to Java doc style comments. 1:35
    The annotation we're gonna write will not only allow us to fully document our code, 1:40
    but it will also allow us to write code that analyzes the presence of 1:44
    the documentation itself. 1:47
    This will be possible because annotations, 1:48
    as opposed to standard Java doc style comments, are actually Java code, and 1:51
    as such, we can interact with it using more code. 1:55
    So, how are we going to do this? 1:58
    Completing this project will be a three step process. 2:01
    Number one, writing the annotation itself. 2:04
    Number two, adding the annotation to classes and methods. 2:06
    And number three, writing code to check for 2:09
    the presence of annotations on classes or methods. 2:11
    Let's get started. 2:13
    Before we start coding our annotation, let me give you a general layout of 2:15
    the project as it relates to the three steps I just mentioned. 2:19
    For the first step, we'll be working in Doc.java. 2:22
    This is the file that contains the definition of our custom annotation. 2:25
    The second step involves annotating a class with this doc annotation, 2:29
    and the class we'll be annotating is called MathUtils. 2:33
    Don't worry, I won't ask you to do actual math. 2:37
    For the third step, 2:41
    we'll write code that determines whether a given class contains our annotation. 2:42
    This code appears in DocProcessor.java. 2:45
    Finally, we have a main class. 2:49
    This contains a main method that we'll use to run our application. 2:52
    Let's go back to the DocProcessor class for a moment, 2:56
    to take a closer look at what's happening. 2:58
    There's a bunch of code in there already, so I want to give you a chance to absorb. 3:01
    Essentially, we'll first look for the annotation on the class. 3:05
    The documentation for that is on line 24. 3:07
    Then analyze any non-private methods. 3:10
    That's on line 36. 3:13
    We'll check for annotations on those methods. 3:15
    We're not concerned about documentation of private methods here, only what others 3:19
    might use, like public or protected, hence my reference to non-private. 3:22
    Looking even closer, we'll check to see that each non-private 3:28
    method has the correct number of parameter descriptions, documented on line 49, 3:30
    and a return description where necessary, documented on line 58. 3:35
    To get a better understanding of the logic, you might wanna 3:40
    take a few moments to scroll through the code before starting the next video. 3:43
    I'll be right here when you return. 3:46

    You need to sign up for Treehouse in order to download course files.

    Sign up

      You need to sign up for Treehouse in order to set up Workspace

      Sign up