Question & Answer
Question
How do you know when to use different annotations effectively in IBM Rational Rhapsody, and what considerations should be given to use these annotations manually in your code?
Cause
The preserve annotation was introduced in Rhapsody 7.6.1 in aim to address certain issues related to Reverse Engineering (short: RE) and RoundTrip. Below are some of examples:
- RoundTrip Parser fails to analyze complicated macro expression even if the particular section is enclosed by ignore annotation.
- Incorrect use of ignore annotation could result in an unexpected update to the model.
- The section enclosed by ignore annotation can't be updated from the model.
Introduction of preserve annotation has caused confusion about the differences among annotations as users can have difficulty in understanding how and when they should be used, and when not.
Answer
Topic: Preserve vs Ignore vs Auto-generated
- Preserve annotation
C++ | C |
| //#[ preserve ... //#] preserve | /*#[ preserve*/ ... /*#] preserve*/ |
Usage: The preserve annotation indicates whether the contents of the code region are to be preserved when code is regenerated. The code inside the preserve section is modelled as a text fragment into Source Artifact, so RE/RoundTrip will not model it as a model element. The text enclosed by preserve annotation can be modified by RoundTrip. See the image below showing how the annotated code is represented in the model:
The preserve annotation is recommended to use if you have code fragment you do not want in the model but want to keep in the generated code for testing, debugging or analysis purpose. There is a certain rule applied for the code you can enter within the preserve block. For more information, see the related technote 1640085.
- Ignore annotation
- Auto-generated annotation
C++ | C |
| //#[ ignore ... //#] | /*#[ ignore */ ... /*#]*/ |
Usage: This annotation does not work with RE, only works with RoundTrip. The code inside the ignore annotation will not be modelled nor saved in Source Artifact, it is completely ignored by RoundTrip, although still being parsed. It is primarily used by Rhapsody code generator to generate code that should not be modelled via RoundTrip. As a typical usage, Rhapsody code generator adds ignore annotation for a user-defined type declaration which can not be removed or changed on RoundTrip. From the code customization point of view, the use of "ignore" annotation is useful for string properties that go to the generated code but not modified by RoundTrip like prefix and suffix properties, template description, and so forth.
Note, if you are adding symbols or macros between these annotations they will also be ignored unless you add the symbol or macro to the <Lang>_ReverseEngineering::Parser::Defined property at the configuration level.
C++ | C |
| //## auto_generated | /*## auto_generated */ |
Usage: This annotation does not work with RE, only works with RoundTrip. It is similar to ignore and used by Rhapsody code generator for element that are auto-generated and RoundTrip don't take them from the code back to the model. Common cases where this annotation is used for are implicit dependencies, attribute's mutators and accessors.
Topic: When/Where can annotation be used?
- The preserve annotation can be used to save user code in the model as textual information that remains preserved in the forward code and modifiable via RoundTrip.
- The ignore annotation can be used in string properties that go to the model but not modified by RoundTrip.
- The auto-generated annotation should not be used by anyone except Rhapsody unless you customize Rhapsody's default code generation using Custom SDK.
There are examples of this that ship with Rhapsody in the ...\Samples\CustomCG Samples directory. Note that if you customize code generation in a way that Rhapsody's default simplification does not take place, then it is your responsibility to manage the annotations, or avoid using RoundTrip and Instrumentation (such as animation).
Scenario: Reverse Engineering:
The only annotation that can be in code for RE is preserve annotation. Other annotations will result in unexpected behaviors - preserve annotation can be placed relatively freely in the code. The main limitation would come when the code outside the annotation remains semi-compilable code like below:
void foo (int x ,
//# [preserve
int y);
//#]
Importing such code via RE will cause problem in the modelling of the function "foo", and may cause unexpected behaviors.
Scenario: RoundTrip:
All of 3 annotations can be used with RoundTrip.
Topic: What effect does annotations have on RE/RoundTrip?
- The preserve annotation is the only annotation that can be used together with RE, other annotations will result in unexpected behaviors.
- All those annotation cause RE/RoundTrip not to model elements inside them.
- The preserve annotation creates text fragment into Source Artifact (like a global comment), ignore and auto-generated annotation do not RoundTrip into the model at all.
Topic: What is Source Artifact (SA)?
Before version 7.2 of the product, a SourceArtifact was referred to as a component file. While component files still exist, they now refer to elements under the Components category in Rational Rhapsody. When component files are located under packages or classes, and so on, they are referred to as SourceArtifacts.
RoundTrip is a powerful feature Rhapsody provides. RoundTrip refers to an activity to reflect changes you made to the source code back into model, and vice versa. Such changes typically include mapping and ordering information, and code snippets. When you make a change to source code, Rhapsody will analyze the source code and determine the type of change you made, and model it correctly. If the change was considered as something that is not appropriate to be modeled, for example a comment, Rhapsody will store that information as a textual information in Source Artifact.
Source Artifact is normally created at the time of round-tripping and used for ordering and various manipulations. It serves the role of information holder. Note that Source Artifact created by RE/RoundTrip are signed as synthesized with the small 's'
. If user make changes to the Source Artifact, it stopped to be synthesized ('s' is removed). If it is not synthesized, Rhapsody will treat the particular Source Artifact more carefully, same as it was not automatically added by RE/RoundTrip, and thus RoundTrip will not change its location nor delete it automatically. In general, Source Artifacts are managed by Rhapsody, user can add new Source Artifact in order to affect the generated code, but bear in mind it could be altered by RoundTrip.
For more information about Source Artifact and preserve annotation usage, refer to the IBM Rational Rhapsody Information Center documentation for your installed Rhapsody version in the following topics:
Consideration: There is a property <LANG>::ModelElement::SimplifyInstrumentation which can disable generation of annotations (by setting it to None). But, you should be aware that some code related functionality like RoundTrip, error highlighting, locating a line in the code may not work as expected as result of disabling annotation insertion.
Related Information
Product Synonym
Rational Rhapsody
Was this topic helpful?
Document Information
Modified date:
27 May 2022
UID
swg21632630