Guidelines for API Deprecation

What "Deprecated" Means

The need for deprecation comes about because, as a class evolves, its API changes. Methods are renamed for consistency. New and better methods are added. Attributes change.

When doing minor version code upgrade from version 1 to version 2. The basic need is  to go through proper deprecation process that will ensure that the developers using the API will get quality help to quickly uptake all changes and can easily make transition to a new version.

SysObsoleteAttribute Tag

—  Used to mark a method, class, or table as obsolete.

—  Compiler issues either an error or warning when it encounters use of an item - marked with the SysObsoleteAttribute Tag.

—  

Syntax:

[SysObsoleteAttribute(str_Message, bool_isError)]

Where str_Message is the user friendly message that you want to display.

Deprecating Existing Method

—  These guidelines are applicable for public and protected modifiers only.

—  Deprecating a Method.

1.       Mark the method with SysObsoleteAttribute attribute

2.       Remove all code from the method.

—  For methods that return non void value you should place the following code in method body.

throw error(Error::wrongUseOfFunction(funcname()));

Cases when deprecation is mandatory

1. Return type changed.
2. Number of parameters changed.
3. Parameter types changed.
4. Access modifier became more restricted.
5. Parameter order changed.
6. Parameter changed from optional to mandatory.

     For all above cases the method should be deprecated and a new one should be introduced.

In case of Adding New Parameters

1. Parameters should be added as the last ones in the parameter list.
2. In case of adding a new parameter with a default value the deprecation is not necessary.

Deprecating Existing Classes

—  These guidelines are applicable for public and protected modifiers only.

—  Deprecating a Class.

1.       Mark the class declaration with SysObsoleteAttribute attribute

2.       Remove all the code from the class declaration.

3.       Remove code from all the methods.

Deprecating Metadata Artifacts like Enums, EDTs

—  Changing EDT type of fields

—It is Not recommended.

If the change is absolutely necessary it should be documented.

—  Deprecation of Enum items

It is not Not recommended.

— If the change is absolutely necessary it should be documented.

—  Deprecation of Table fields

—  Don’t Delete Fields.

—  In case of renaming field document every single field rename.