1

I'm developing a mini framework and I want to perform changes to existing methods. I know in order to deprecate a method I can use the @deprecated annotation. However, what annotation should I use to let the users know that I'm going to change the amount of parameters a method will receive or maybe the returned result?

I'd like to know what annotations to use in PHP.

  • 1
    Java and Php are very different languages and the conventions of one don't necessarily apply to the other (nor are the experts of one always familiar with the other). Is there one you could ask about in this question? – user40980 Feb 20 '14 at 3:48
  • @MichaelT When it comes to knowledge I have no language preference :) Right now, I would need the PHP answer more than the Java one. However, I would like to know the answer for Java too and I feel like asking a so very similar question twice wouldn't make any sense. I guess Java experts can answer the Java one and PHP experts can answer the PHP one. – Mosty Mostacho Feb 20 '14 at 3:51
  • The java question and the php ones are separate questions. I would suggest editing this question to be one or the other, and see how well that gets answered (I wouldn't suggest asking them both at once as any problems with one would mean the other one would have the same problem - better to ask once for one, fix as necessary and then ask the other with the additional information you know). – user40980 Feb 20 '14 at 3:53
  • Sounds fair to me. – Mosty Mostacho Feb 20 '14 at 3:55
1

Assuming you're using versioning, you should make a note of breaking changes in the changelog when it occurs, and announce the breaking change a version ahead of time (or a couple versions ahead of time depending on how widely your project is used). If all you're doing is expanding an existing function signature and can get away with having the new parameters being optional then you don't need to announce this, but might still want to consider putting it in the changelog.

To put it plainly, function signatures can't be deprecated in PHP. You can deprecate an entire function, but not a signature, since PHP functions only have one signature.

Perhaps keep the old method and have the new signature in a function with a transitional name, like "foo()" and "_future_foo()" and wait for the next-next version to replace the old one with the new one. This might complicate things, so it would be best to do what the PHP devs do and just announce the breaking change a version (or two) ahead of time.

If you find yourself changing a function signature and its return type completely, consider instead making a new function and leaving the old one alone, but mark the old one as deprecated. For that, yes, you would use @deprecated

| improve this answer | |
1

Depreacated does not meen you have a solution yet.

In Java hide() and show() are deprecated since years. The documentation force us to use setVisible(boolean) instead while hide() and show() - anyway hide() and show() are still working good.

@deprecated does not throw a exception, its a warning for developers.

Whenever a method do not exists anymore: a Java-Unittest will fail - but this test must has been written by the people who use your mini-framework.

Also to give info about backward-compatibility: java has a @version-annotation.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.