+1
I think we should make it a habit to convert all Geode code as part of the
pull request that introduces the deprecation so that this is not left as a
low priority item for some later point in time.
Something to look for when reviewing pull requests IMO.
On Sun, Mar 15, 2020 at 9:41 PM Jacob Barrett <jbarr...@pivotal.io> wrote:
> Hey Team,
>
> When deprecating a symbol, like class or method, please included a
> reference to the replacement in the java docs. Also please include an
> example of converting from the old API to the new. I am finding many many
> places in the source where deprecated code has no hints at all. As many of
> us don’t take the effort to immediately convert old tests over to the new
> APIs the context is lost when someone finally does get around to it. For
> public APIs this is extremely important so that users know how to migrate
> their code with as few roadblocks as possible.
>
> Here is an example of something that is much better than most of what I am
> seeing.
>
> /**
> * @deprecated Replaced with something better and safer.
> * Replaced by {@link Bar}.
> */
> @Deprecated
> class Foo {
> /**
> * Do something.
> *
> * @deprecated Replaced with something better.
> * Replaced by {@link Bar#doSomethingBetter()}
> */
> @Deprecated
> public void doSomething() {}
>
> /**
> * Do something.
> *
> * @deprecated Implementation is not safe.
> * Replaced with {@link Bar#doSomethingBetter()} and {@link
> Bar#doSomethingElse()}.
> * Migration example, replace:
> * <pre>{@code
> * Foo foo = new Foo();
> * foo.doSomethingAndSomethingElse();
> * }</pre>
> * with:
> * <pre>{@code
> * Bar bar = Bar();
> * bar.doSomethingBetter();
> * bar.doSomethingElse();
> * }</pre>
> */
> @Deprecated
> public void doSomethingAndSomethingElse() {}
> }
>
> class Bar {
> public void doSomethingBetter() {}
> public void doSomethingElse() {}
> }
>
> -Jake
>
>
--
*Joris Melchior *
CF Engineering
Pivotal Toronto
416 877 5427
“Programs must be written for people to read, and only incidentally for
machines to execute.” – *Hal Abelson*
<https://en.wikipedia.org/wiki/Hal_Abelson>
