Would adding an @beta doc-comment tag be useful? [closed]

Question

When a function has reached the end of its life, we add a @deprecated tag into its doc-comment to notify other developers that they should stop using this function, and then a couple years later it's removed.

I was just thinking about an @beta tag to signify this method is brand new and hasn't been tested in a variety of use-cases yet.

You might be thinking "you can write use-cases to ensure its correctness!" Of course you can, but its the API that concerns me, and how it behaves in edge-cases. Sometimes these decisions are not obvious until you have tried out the function in a variety of situations. Sometimes new parameters need to be added to cover more use-cases. Sometimes re-ordering them makes sense if you find that an argument is actually optional and needs to be moved to the end (or vice versa).

By adding the @beta tag, you are warning other developers that the API of this method might change yet, and they should use it with extreme caution. This gives you more granular control over your API instead of making the entire project 'beta'.

To get the most use out of this, however, IDEs and documentation-generators would need to pick up on this tag.

What do you guys think? Could you see this as being useful, is it a waste of time, or do you have other ways of dealing with this?

In the past, I have made such methods 'private' where possible, or prefixed them with an underscore.

Answer 1

It is not just a waste of time, it is a huge waste of time.

There is a big difference between @beta and @deprecated. Using @deprecated is fine: it informs users of the API that the method, function or class will no longer be used in the future. The deprecated state will never change until the code block is deleted from the active source code. Deprecating code is the secondary result of newer code. The overhead of marking code as deprectated is reminding which code is replaced and planning when to remove it. It is impossible to forget to remove the @deprecated flag, because deprecated methods are in their end of life phase. You could argue that code can also be undeprecated, but then you should seriously consider the stability of your API.

@beta would inform users of the api that they can use a API member at their own risk. Forgetting to remove the flag from the documentation results in a huge waste of time for the users, since they will be reluctant to use newer methods that save them development time. It is also redundant from an API programmer perspective, because with a decent version control system (that is decently used), you can get an overview of what changed since the last stable release.

Which brings us to releases. If the quality of a code block is poor or too new or too unstable or too anything, then it shouldn't be released as stable code. In the minds of the API users, the weakest link in the API will tear its reputation down, even if marked as such in the documentation. The more adventurous users who like danger and hidden features may want to get hold of a beta release.

Oh, and don't say "but my users are very intelligent and will make the difference", because, well, let alone the intellect of the API users, which may be above moderate, they will prefer a clean, stable API over anything else for serious work.

The solution to this problem lies more in the lines of intelligent use of distributed version control and release scheduling than in documentation, which not always evolves in sync with the source code development.

Answer 2

I actually like your suggestion. It is sort of a pre-cursor to adding something like the word 'final' in-front of a function. It makes a lot of sense, and while the above comments suggest having use and test cases is prudent, often times in the real world we can't create or even see every test case until something comes up.

Answer 3

You shouldn't add untested or unstable features to a stable API. Instead, add them to a beta/testing branch and when they're tested enough, add them a new stable version. Otherwise, users of your stable API will have to constantly be checking whether or not the methods they're using a stable.