It’s often desirable to replace a class or method with one that provides similar or identical functionality. This could be because the implementation has been improved, or simply because a more intuitive name is desired. However, when the change affects other programmers, it might not be convenient for them to migrate all their code to use the new class or method immediately. As a result, it’s helpful to have a mechanism for identifying code that should be avoided and could be eliminated in the future. Java’s @deprecated tag serves this function.

The @deprecated tag is placed within the javadoc-style comments for a class or method, and actually serves two purposes. First, it provides a visual cue within the comments to notify programmers that the construct it is associated with should be avoided. Second, it is detected by Java compilers, which can issue a warning message when encountering a reference to the deprecated class or method. In this example, the name() method has been deprecated and effectively replaced by getName():

 	private String name;	/**	 *	Returns the name associated with this instance	 *	@return		Name associated with this instance	 *	@deprecated	 *	@see	getName()	 */	public String name() {		return name;	}  //  public String name()	/**	 *	Returns the name associated with this instance	 *	@return		Name associated with this instance	 */	public String getName() {		return name;	}

Notice that the name() method still exists and will function, so any code that calls it won’t break. However, references to it will be flagged with a warning message when they are compiled, at which point it is the programmer’s responsibility to identify the replacement (in this case the getName() method identified by the @see tag) and make the appropriate changes when feasible.