有用的 Java 注释

Question

I'm interested in finding out exactly which Java annotations people think are most useful during development. This doesn't necessarily have to limited to the core Java API, you may include annotations you found in third party libraries or annotations you've developed yourself (make sure you include a link to the source).

I'm really interested in common development tasks rather than knowing why the @ManyToOne(optional=false) in JPA is awesome...

Include the annotation and a description of why it's useful for general development.

Answer 1

I doled out a bunch of upvotes for other users, but just to give my two cents the only three annotations I use with any regularity in development are the main annotations used directly by the compiler:

@Override - Great for making it explicit in your code when you're overriding another method. Also has the extra benefit of being flagged as a compilation error if you don't override a method the way you think you are (see this other SO post ). This flag informs the compiler that you're intending to override something, so if you don't (eg you forget an argument in the method signature), the compiler will catch it.

@Deprecated - Indicate whatever you're marking as something that should not be used from this point forward. The compiler will generate warnings for use of any code elements you've marked as deprecated. In general, deprecation says "this was in here in the past, but it may go away in a future version." Make sure you also use the associated "@deprecated" Javadoc flag in conjunction with this too to tell people what they should use instead.

@SuppressWarnings - Tell the compiler to suppress specific warnings it would otherwise generate. This can be useful for things like when you intentionally want to use deprecated methods, you can block out the deprecation warning. I tend to use it a lot to block out everyone's favorite "Serialization UID" warning on serializable classes (whether or not you should do that is another debate for another time). Just handy for those cases where you know something you're doing is generating a warning, but you're 100% sure it's the proper behavior you want.

Look at the Sun Annotations Guide and check out the section "Annotations Used by the Compiler". These three are given a fairly lengthy discussion.

Answer 2

The Java Concurrency in Practice annotations

Very useful for describing exactly how your code is or isn't thread safe...

Answer 3

I find the he concurrency-related annotations defined by Brian Goetz in his book "Java Concurrency In Practice" to be very useful:

• @GuardedBy
• @Immutable
• @NotThreadSafe
• @ThreadSafe

They're particularly useful as FindBugs has patterns that use them.

A jar and documentation is freely available at http://www.javaconcurrencyinpractice.com/

Answer 4

@Override has my vote. It makes it instantly clear what your method is about and makes your code more readable.

Answer 5

@Test

( JUnit 4 ) It's made writing and understanding test files quite a bit cleaner. Plus, the ability to add the expected attribute has saved a few lines of code here and there.

Answer 6

@Deprecated

Introduced in Java 5 .

• It helps developers see what's deprecated in IDEs. (Prior to this, most IDEs could still pull a @deprecated out of the javadoc comments for a particular method, but this annotation was a nice way to make it meta-information about the method itself, rather than a comment in documentation.)
• It's also used by the compiler to print out warnings when you're using deprecated methods.

Answer 7

Personally I've been looking at the JSR303 Bean Validation and the annotations it provides, I imagine these will become more commonplace, there's only a few implementations of the JSR so far, but they provide annotations such as:

@NotNull private String name;
@NotNull @Size(min = 5, max = 30) private String address;

More info here: http://jcp.org/en/jsr/detail?id=303

Answer 8

these should be useful, you can define them in your projects to better communicate intentions:

• @ThreadSafe
• @Immutable
• @ValueObject
• @BagOfFunctions (eg java.util.Collections)
• etc

Answer 9

Here are some Annotations I use in day to day development

Spring:

1. @Autowired - used to Auto wire beans
2. @Rollback - If set to true it will rollback all DB operations done inside the test case

JUnit:

1. @Test - Tell that a method is a test case
2. @Ignore - If you want to ignore any of the test cases
3. @Before - Code that should run before each test case

JPA:

1. @Entity - To tell that a POJO is a JPA Entity
2. @Column - Map the property to DB column
3. @Id - tell that a java property is Primary key
4. @EmbeddedId - Used for Composite Primary Keys
5. @Transient - This property should not be persisted
6. @Version - Used to manage optimistic locking
7. @NamedQuery - Used to declare Native SQLs
8. @OneToMany - One to Many relationship
9. @ManyToOne - Many to one Relationship

I have included only the most essential ones.You can find details about all the JPA annotations from the following links.

http://www.oracle.com/technology/products/ias/toplink/jpa/resources/toplink-jpa-annotations.html

http://www.hiberbook.com/

Answer 10

We started using a compile time tool called lombok ( http://projectlombok.org/ ). You annotate classes, members, etc. and methods are automatically generated at compile time. It's a great productivity boost and saves hundreds of lines of tedious coding.

Do you want a toString() method to be automatically generated? Just annotate your class with @ToString .

Tired of having to define getters and setters for your members? Annotate your class with @Getter and / or @Setter and they're automatically added.

Want to have an SLF4J logger to log stuff? @Slf4j creates a private static final logger for you.

@Data
public class MyBean {
    // Getters for x and y, setter for y and constructor with x as arg automatically created!
    // toString() and hashCode() methods are there too!
    private final int x;
    private int y;
}

.

@Slf4j
public class SomeClass {
    public void doSomething() {
        log.info("I've got log.");
    }
}

Setting it up is very easy: just add a provided maven dependency. There's also a tiny Eclipse / IntelliJ plugin.

Check out the full list of features there: http://projectlombok.org/features/index.html

Answer 11

Junit 4 provides very useful annotations. Here's a tutorial illustrating the usage of annotations to define tests.

eg

@Test(expected= IndexOutOfBoundsException.class) public void empty() { 
    new ArrayList<Object>().get(0); 
}

As Dan pointed out below, TestNG did this originally.

Answer 12

@Given

allows one JUnit test to build upon the return value of another test. Requires JExample .

Answer 13

I started a weekend project to implement a Programming By Contract framework using method and parameter annotations eg

//...
myMethod (@NotNull String a, @NotNullOrEmpty String b){
     if ( !validate() ){
         //raiseException
     }
}

I got stuck at the point of getting param values automatically. Java reflection does not have it. never understood several people's ranting on Java till I came across this limitation.

Answer 14

@FunctionalInterface

Useful to communicate that a particular interface is meant to be functional. If the single abstract method is removed, it'll throw a compilation error.