每當妳棄用某方法時，創建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時沒有考慮到未來的變動”而感到愧疚。沒有人能完美的預見未來。畢竟，如果妳知道未來，生活就無趣了。