Submitting Examples: Creating the Example

Create a New Example

Now that you have a clone (local copy) of the forked repository you want to contribute to, you can start editing examples. In this section we explain some conventions to follow when creating or modifying an example.

Under rticommunity organization in GitHub you will find different examples repositories—they include -example in their name. Each of these repositories corresponds to an RTI product (e.g., rticonnextdds-examples corresponds to RTI Connext DDS Core). Make sure you choose the right repository before adding a new example.

In the following lines we describe the rticonnextdds-examples repository structure to give you an idea of the conventions we follow. As you can see, all the examples included in the repository are placed under the examples directory. Each example directory contains a README.md file with some documentation on the example, and a set of subdirectories with the implementation of the example in different languages. Each implementation of the example contains extra documentation on how to build and run the example in that language.

rticonnextdds-examples/ — Top level directory.
- README.md — Description of the repository. This description is parsed and used in the GitHub website.
- examples/ — Directory containing all the examples in the repository.
  - content_filtered_topic/ — Example on how to use Content Filtered Topics. We use snake case (in lowercase) for our directory names. Note also that we use lowercase for languages directory names (e.g., c, c++, java).
    - README.md — Describes the concept the example illustrates and the overall architecture/approach used by the example. This description is common to all the languages.
    - c/ — C implementation of the example
      - README.md — Explains how to build and run the C example. README.md files under each language's folder (e.g., c, c++, java, etc.). These files include specific instructions for each of language.
      - USER\_QOS\_PROFILES.xml — QoS XML file pre generated using rtiddsgen. It should only be included in the example if it has been modified to include new QoS settings. You should illustrate, as we indicate below, how to modify these settings both via XML and programmatically.
      - cft.idl — Sample IDL file. IDL files should be named after the example name. If the example name is too long you may use an acronym. The data type should be named after the example name as well.
      - cft_publisher.c — Publisher application modified from the file generated using rtiddsgen. Do not include the Publisher application if the file generated does not need to be modified.
      - cft_subscriber.c — Subscriber application modified from the file generated using rtiddsgen. Do not include the Subscriber application if the file generated does not need to be modified.
    - c++/ — Traditional C++ implementation (C++98)
    - c++03/ — Modern C++ implementation (C++03)
    - cs/ — C# implementation
    - java/ — Java implementation
  - polling_read/

Naming your example

Choose a self-explanatory name for your example. Our goal is to make it easier for users to find something matching their use case. Remember to use snake case (in lowercase) in directory names.

Coding your example

When coding your example take into account the following guidelines:

IDL file, Data Type, and Topic names.

IDL files and Data Types should be named after the example name. If the example name you may use an acronym. For instance, in the Content Filtered Topic, we created a cft.idl IDL file with the following data type:
```
struct cft {
    long x;
    long count;
};
```
In simple examples—just one topic per data type—leave the topic name generated by rtiddsgen by default (e.g., "cft Example"). This will make it easier for users to create sample publisher/subscriber applications using the IDL file. In more complex examples with different topics, use self-explanatory names to make the example easier to understand for users.
QoS properties should be modified via XML (but we should also show how to modify them programmatically).

Many of the features that may be illustrated in our examples require tuning different QoS settings, which can be done either programmatically or via XML.

The convention in the examples repository is to modify these QoS settings via XML, making the code more readable. However, you should also include in the publisher and subscriber applications—in comments—how to modify these QoS settings programmatically, so users can modify them uncommenting the code.
Leave the generation of makefiles and Visual Studio projects to rtiddsgen.

Ideally, you should only check in an IDL file, and the Publisher or Subscriber code and QoS XML file generated by rtiddsgen. For instance, in the Content Filtered Topic C example we checked in the following files:
- README.md
- USER_QOS_PROFILES.xml
- cft.idl
- cft_publisher.c
- cft_subscriber.c
This way, users only need to run rtiddsgen -example <architecture_name> to generate a makefile or Visual Studio project they can use to compile the code, which makes it easier to support more platforms than with custom makefiles.
Document the compilation of the example for every single language.

Example subfolders for every language include a README.md (see Content Filtered Topic C example directory structure above). These files include instructions on how to build and run examples on that language. You can follow the structure of the following existing documents:
In some cases, the makefiles or Visual Studio projects generated by rtiddsgen will need to be modified to include more files or special flags. Make sure to document these changes in the README.md.
Other considerations
1. Keep things as simple as possible.
  
  It is important to keep the focus on the feature that you are trying to illustrate.
2. Focus on one single language first.
  
  It is better to implement a great example in one language than implementing a good example in ten languages. You can always iterate and translate the example afterwards. Other people can contribute on this later as well.

Documenting your example

README.md

Every example must include a README.md in the example's top directory describing the example and the concept it illustrates. This document must provide enough information for users to know whether the example meets their needs without looking at the code. We will use the contents of this file later to include the example in the RTI Community Portal examples section.

Your README.md should follow this structure (you can take Time Based Filter example README.md file as an example)

Example Code -- Name of Example
Concept

Explain the concept the example illustrates. For instance, if your example describes the use of Time Based Filters, describe what Time Based Filters are.
Example Description

Explain how the code applies the concepts explained above.

Comment your code

Comment your code when coding the example—do not be shy. Please, take into account that the example may be browsed by many kinds of users, including people that know nothing about our product. Use following tips to decide when and how to add a comment:

Explain what you want to achieve with your code instead of just explaining what the does does. That is:

/* send_period sleep of 0.25 seconds, i.e., the loop where we write
 * new samples will sleep for 0.25 seconds every iteration.*/
struct DDS_Duration_t send_period = {0,250000000};

as opposed to:

/* Send period */
struct DDS_Duration_t send_period = {0,250000000};

Do not use C++-style comments in C.
Comment out the code to change QoS settings programmatically.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly