沒有什麽事情比看到一個沒有任何說明的@deprecated標註更讓人憤怒的事情了。這種做法只能讓人困惑，我到底還要不要用這個已經‘廢棄’的方法？如果開發者不希望某個方法再被人用的話，就要好好地為@deprecated標註寫說明。這篇文章就討論了正確地使用@deprecated 標註需要遵守的一些規則。

什麽是使用@Deprecated標註的規則?

Rule #1: do Javadoc how not to

每當你棄用某方法時，創建JavaDoc告訴其他程序員如何不再使用這個方法。不要只說“這個方法廢棄了，不要用它”。因為這就是廢棄標註和JavaDoc中@deprecated的字面意義，完全沒有必要再重復一遍。Java開發人員作為目標受眾，都知道deprecation的意思。

命名新的方法，取代舊有的。(使用@link標註!)這可能還不夠，新的方法對應的文檔將解釋如何使用它。不要在JavaDoc中重復（其字面意義），文檔也應遵從DRY原則。另一方面你可能想要描述怎樣替換掉舊方法的調用，你可以就重構的細節給出提示。

Rule #2: do not Javadoc how to

移除過時的JavaDoc文檔。有些人可能爭辯：維護遺留代碼的用戶可能還會需要這些文檔。事實上，他們使用的是舊版本庫中的舊版本方法。舊版本的文檔仍舊存在那裏，像被刻在石頭上（更確切的說是刻在資源倉庫的某個版本上）。含有被廢棄掉的方法的實際版本不應包含過時的描述文檔，那會鼓勵程序員去繼續使用。對於廢棄的方法，只有一種用法：不去用。JavaDoc應該被實時描述，如同rule#1所述。

Rule #3: 不要在JavaDoc中解釋

不要在JavaDoc中解釋為什麽方法被廢棄了。你是一個可靠的的開發，這是你的決定，你的選擇，其他人只能忍著。如果願意，可以寫一篇博客記錄這次調整的決策背景。這可能有幫助，但它不應被寫在JavaDoc中。

JavaDoc的Deprecated API專用來講解如何不再使用。 重點是如何(how)。而不是“為什麽不再使用它(why)”。

Rule #4: do deprecate

如果你覺得需要棄用一方法，那就去做吧！如果你害怕你的用戶，或不想因你廢棄掉一些方法導致你用戶體驗更加痛苦，這個決定將讓你自己痛苦。盡你所能去讓API維持長久的穩定。但如果有需要被廢棄的：立刻扔掉它。不要因“為何當初設計API時沒有考慮到未來的變動”而感到愧疚。沒有人能完美的預見未來。畢竟，如果你知道未來，生活就無趣了。

原文鏈接： javacodegeeks
翻譯： ImportNew.com - dust_jead
譯文鏈接： http://www.importnew.com/10113.html

如何正確地使用Java的@deprecated標註