I think Java's (!) policy for deprecation is good: Deprecation is (mostly) for functions that are error prone or otherwise dangerous. Unless the cost of keeping the function is large, removing functions should be avoided. The docs can point to the newer functions, but DEPRECATION pragmas will just add noise to users' compiles.