Lab: Tekkotsu and Software Engineering

From Tekkotsu Wiki

Jump to: navigation, search

This lab will examine how software engineering principles apply to the Tekkotsu robotics framework.

Browsing the Documentation

Tekkotsu is a large software system, with roughly 700 classes and over 3500 web pages of documentation. You can't read it all. Instead, you will need to learn how to browse the documentation to find the information you need.

From the gray navigation bar at the top of any Tekkotsu.org web page, click on Reference to visit the reference section. You will see a directory of choices at the top, with tabs such as NameSpaces, Classes, and Files, and a little navigation frame running vertically down the left hand side. These perform similar functions.

  • To look up a class: Click on the Classes tab in the top nav bar, or the Classes link in the left navigation frame, and you will see a detailed listing of all Tekkotsu classes with brief descriptions. Click on the Class Index sub-tab, or open the Class List folder in the left navigation frame, to call up a more compact alphabetical list of all classes in the main Tekkotsu namespace. Note: entries are alphabetized by classname, ignoring any namespace qualifiers. Thus, FreeMemReportControl comes before AprilTags::Gaussian because F comes before G. Try clicking on the SoundNode class to view its documentation. Note that the documentation includes an inheritance diagram showing the parents of SpundNode. (If there were any child classes, they would be shown as well.) These classes are also clickable.
  • DualCoding vision classes: The dual-coding vision system resides in the DualCoding namespace. From the main online reference page, under "Sub-Library Documentation", click on "DualCoding". Then you can examine the classes or type something in the search box to learn about vision classes such as Sketch, Shape, LineData, etc.
  • To browse classes: In the navigation frame at left, click on the + sign or the little folder icon next to Class List. This opens up the list of classes so you can scroll around and click on any item. Again, items are listed alphabetically by class name, ignoring any namespace qualifiers. Click on CompletionTrans; that item will be displayed in the main frame. You can continue to click on items in the navigation frame to jump to different items in the list. Click on the - sign or the folder icon to close the Class List folder.
  • To browse classes from the main frame: Click on the Class Index or Class Hierarchy tab under Classes. This displays a compact alphabetical list of just the class names, while Class List includes short descriptions.
  • To look up a class member: Click on Class Members under the Classes tab at the top of the main page, or Class Members in the navigation frame at left; this will take you to the Class Members - All subtab. Using the expanded menu at the top of the main frame, you can restrict the listing to a certain type of class member (Functions, Variables, Typedefs, Enumerations, etc.), or jump to a specific letter in the alphabetical listing. Select the letter b and scroll down to buttonEGID and click on its EventBase link. You will see that buttonEGID is an enumeration value of type EventBase::EventGeneratorID_t.
  • To find a class's parents and children: Click on the Class Hierarchy sub-tab of the Classes tab, or on Class Hierarchy in the left navigation frame, and do a search for the "Transition" class. Below it you will find all the subclasses of Transition. If you click on the Transition link you will be taken to the documentation for Transition, which begins with a graphical depiction of the class, its immediate parent class(es), and its immediate child classes. Boxes outlined in red indicate additional levels of the hierarchy have been suppressed; click on a box to move up or down the hierarchy.
  • To look at a source file: Click on Files in the top navbar, or File List" in the navigation frame at left, to call up a listing of all the Tekkotsu source files and their descriptions. Or, in the left navigation frame, open the "File List" folder to just see a list of file names. Either way, clicking on StateNode.h will show you information about that file, including the dependency gaph that shows its relationships to other files. Clicking on the "code" link will show you the actual source code, with nice syntax highlighting. You will also find links to the source file included in the description of every class member.
  • To look up namespace info: When you want to look up information on the various namespaces included in Tekkotsu, click on the Namespaces tab or open the Namespace List folder in the left navigation frame, and then click on the namespace you want to examine. Look at the CreateInfo namespace for information about the Create robot configuration, or the CalliopeInfo namespace if you're using a Calliope robot.
  • The search box in the upper left hand corner is a quick way to look up an identifier. It will prompt you with candidates in a pop-up menu as you type. Click on an entry to narrow your search.

Exercises:

  1. Where is PlayButOffset defined? (Use the search box.)
  2. What are the parent and child classes of NullTrans?
  3. Where is the setSound() method defined, and what does it do?

Searching the Source

Another way to navigate through Tekkotsu is to search the source tree. Tekkotsu provides a tool called ss (for Search Source) that will search all the source files in a directory tree for a specified string. It uses the Unix utility grep for this. So, for example, if you get a runtime error message and you want to find where in the source code this message is generated, you can search for it. Here is an example:

cd /usr/local/Tekkotsu
ss "ing normally"

Exercises:

  1. Where in the source code does PlayButOffset appear?
  2. Where does the phrase "Pilot request" occur in the source?

Coding Standards

In large software projects, programmers adopt coding standards to make their code more readable and consistent. There is no one standard for C++, but the Google C++ Style Guide is a good place to start:

For example, see this section on Conditional statements:

Click on the arrow to expand the topic. Note that there must always be a space between the if and the left parenthesis, and before the left brace. Also, programmers should be consistent about whether they put spaces just inside the parentheses or not. These are two small examples of consistent style. Browse the web site to learn more.

Tekkotsu's style is close to the Google style guide. Some Tekkotsu conventions you will notice:

  • Class names always begin with a capital letter, e.g., StateNode.
  • Method names always begin with a lowercase letter, e.g., doStart.
  • Enumerated type names end with _t, e.g., EventBase::EventTypeID_t.
  • Names use medial capitals (sometimes called 'camel case) rather than underscores to separate words, e.g., EventBase rather than Event_Base or Event_base.


Exercises:

  1. What does the Google style guide say about return values? (Go to the main Style Guide page and look for this topic.)
  2. What does the Google style guide say about use of horizontal whitespace?
  3. What naming convention does Tekkotsu use for data members of a class? Examine some source files or browse the Tekkotsu reference pages to find out.
  4. What naming convention does Tekkotsu use for namespaces? Is it consistent, or are there exceptions?

To learn more, see the article on C++ Coding Advice.