UP | HOME

Homework Guidelines

Overview

These guidelines apply to all homework assignments in ME495 Sensing, Navigation, and Machine Learing for Robotics. This document also serves central location for collecting coding standards for the course.

Important Notice

  1. Failure to adhere to certain guidelines may result in receiving no credit, even for a working solution.
  2. These guidelines apply to every homework assignment but may be overridden by instructions in an individual assignment.
  3. If you are unsure about how these guidelines apply or any assignment instructions please ask.

Homework Layout

  1. Each assignment consists of a list of tasks labeled as X.Y, where X is the task group and Y is the subtask.
  2. All tasks with the same group are related and it makes sense to read over all the tasks in a group prior to attempting to complete any of them.
  3. Tasks within a group are not necessarily meant to be done in the order they are presented.
    • It will often make debugging easier to implement simpler versions of several of the tasks simultaneously and slowly build up functionality
    • You are encouraged to look over all the tasks before starting
  4. Most of the assignments should be viewed as pieces of a single larger project. Therefore, you may need to correct issues on previous assignments prior to moving forward.

Submission Instructions

  1. All homework will be completed in a single git repository
    • I will send everyone an individual link for creating this repository
  2. I will grade whatever commit is at the HEAD of the main branch when I clone your repository.
  3. Maintain a file called Tasks.md.
    • Whenever a task is complete, list it on its own line in this file.

Coding Standards

The following list contains the standards that our code should strive to adhere to.

The list may grow as the quarter progresses so check back for each assignment.

Git

  1. Do not include files that do not belong in git. For example
    • Generated executables, libraries, object files of any kind
    • URDF files generated from xacro
    • Files generated by the build system
    • The build, install, or log space
    • The .vscode directory
  2. Your name/email address should be set properly in git
  3. Each homework assignment should consist of many small git commits.
    • You should include a meaningful commit message with each commit
    • It is okay to commit code with compiler errors to your own development branch, as long as they are not present on the main of any branch.
  4. You may use as many branches as you like, but I will only look at the main branch.

ROS

  1. Your code must pass colcon test
  2. Layout your code as git_repository/package
  3. Within a package: (note: if you have no files that fit in a given category, do not include the corresponding directory)
    • config/ Contains .yaml and .rviz files
    • launch/ Contains .launch files
    • urdf/ Contains .xacro, .urdf, and .gazebo files (but not if they are generated at runtime).
    • src/ Contains the source code for your ROS nodes and libraries
    • msg/ Contains message files
    • srv/ Contains service files
    • include/pkgname Public headers, if you are treating your package as a library
    • tests/ Unit tests and test scripts
  4. Launchfile should not result in errors or warnings due to code in one of your packages.
  5. Launchfile arguments should have a description attribute to explain their use
  6. Any package.xml files should be kept up-to-date with the proper dependencies, a description, and author information
  7. No hardcoded/absolute directories in launchfiles or code. Use $(find-pkg-share) and other tools as appropriate, so that the code can be run on computers other than your own.

C++

General

  1. The code at the HEAD of the main branch should be free from compiler errors (Automatic Zero)
    • Commit messages for intermediate commits with errors should be labeled as DOES NOT COMPILE
    • You will automatically receive a zero for code that does not compile on the main branch or task_x branch.
    • If your code does not compile, do not push it to main (though you may push to another branch)!
  2. There should be no compiler warnings. Take compiler warnings seriously as they often can indicate a bug in your code.
  3. If your program ever segfaults, it has some type of memory corruption that should be fixed immediately.
  4. All C++ code should be compiled with c++17 and -Wall -Wextra -Wpedantic
  5. Put braces after control-flow expressions even if they are one line (see goto fail)

Comments

  1. All .cpp files that are ROS nodes should start with the following comment block: 

    /// \file
/// \brief A brief description of what the file does
///
/// PARAMETERS:
///     parameter_name (parameter_type): description of the parameter
/// PUBLISHES:
///     topic_name (topic_type): description of topic
/// SUBSCRIBES:
///     topic_name (topic_type): description of the topic
/// SERVERS:
///     service_name (service_type): description of the service
/// CLIENTS:
///     service_name (service_type): description of the service

  2. All functions/methods should be commented using doxygen style comments 

    /// \brief Computes the factorial
///
/// \tparam T - An integral type
/// \param F - the factorial to compute
/// \returns F! (F Factorial)
/// <template typename T>
/// T factorial (T F);
  3. Classes should have a doxygen comment block describing what the class does.
    • You should also provide comments for private members (but not doxygen comments), where appropriate
    • Private members are an implementation detail and documentation should not be visible to readers of the main documentation.

Include Files

  1. Use include guards in all header files
  2. All include files that you write should be included with #include"package/headerfile.hpp".
  3. Minimize the amount of header files you place in each header file by using forward declarations where possible

Namespaces

  1. Do not put using statements at file scope in header files.
    • These using statements change the behavior of all code that includes the header, including other headers that are below this one
    • Thus, if you do do this you can introduce include-order dependencies and mess up the functioning of other people's code when they include your header
  2. In most cases it is preferable to explicitly do a using for each function that you need rather than polluting the namespace by doing using namespace std
    • One exception to this rule is when using literal suffixes (e.g., the units from std::chrono)

Math

  1. Double precision literals should always include the decimal point (e.g., 1.0 rather than 1)
  2. Complicated math expressions should be commented, referencing the derivation or source of the equation.
  3. Break up long math expressions. It is okay to store intermediate values as const or constexpr variables

Classes

  1. Constructors should use initializer lists to initialize member variables
  2. Member variables should be initialized in the constructor initailizer list in the same order in which they are declared
  3. Usually single-argument constructors should be declared explicit (so there will not be an implicit conversion)
  4. Do not use this-> unnecessarily. In C++ this is usually implied when working within a member function.

Variables

  1. Use constexpr and const everywhere you can
    • Do not use const in headers for pass-by-value
  2. Place variables in the scope closest to where they are needed
  3. If you use a global variable, make it static or put it in an anonymous namespace so it can't bee seen by other modules
    • There are rare cases where using an extern global variable might make sense, but not in this class, so don't use extern
  4. Use auto a lot (see almost always auto
  5. Do not inherit from a class unless it has a virtual or protected destructor.

Pointers

  1. Resource Acquisition is Initialization
    • This means you probably don't want to be using new except in a constructor or delete except in a destructor
    • There are very few reasons (such as writing your own custom data structure) to use new or delete in Modern C++
      • Alternatives are smart pointers (with make_shared and make_unique instead of new, or more likely std::vector
  2. Prefer pass by (const reference) to pass by pointer. There are very few reasons (such as interfacing with C code) to pass by raw pointer in modern C++

Data-structures

  1. Don't use raw arrays.
  2. The default data structure of choice is std::vector
    • Other data structures may have this or that property, but std::vector almost always can get the job done in the most straight-forward way.
  3. Use the algorithms std::algorithm

  4. When indexing, use .at() to get runtime bounds checking (at the expense of performance)

    • Do not ever use [] to index in a C++ program.

    -At some point you may want to use [] for effiency reasons, but that point is very far down the road.

  5. When using C++20 or beyond, use std::ranges Introductory Tutorial

Citations

If you use any external source (a website or a book, another person, or an LLM or other AI tool such as ChatGPT or Github Copilot), you must cite the source. These are general purpose guidelines, but the next sections discuss the use of former solutions and AI tools.

  1. Create a citations.txt file in the base directory of your repository.
  2. The first line in citations.txt should state who you worked with generally, even if no specific code can be traced back to an individual.
    • e.g., Worked With: Person A, Person B
    • Citations of online resources must include the date it was accessed on.
  3. The subsequent lines should be labeled with a number that can be referred to in source code when cross-referencing
    • If a source inspired a particular piece of code it should be cross-referenced, even if the code was not copied directly.
    • When in doubt, cite and cross-reference. Lack of proper cross-referencing is a violation of this policy.
  4. The only sources that are exempt from the citation requirement are:
    1. Me/anything said by me in office hours or class.
    2. My notes (on any website authored by me).
    3. Anything under https://docs.ros.org/en/iron/Tutorials.html.
    4. Any ROS 2 or package-related "boilerplate" code (i.e., code that is provided as an example for how to use a package/feature that would not vary significantly between different uses).
    5. C++ reference material (e.g., from cppreference.com) that is used in a generic manner (e.g., to help you understand how a standard part of C++ works) need not be cited.
      • However, if you use code examples from cppreference.com these should be cited and cross-referenced appropriately.

Cross Referencing

Cross-referencing properly requires clearly delineating the start and end of such code with comments in the following format:

  • For C++ or C: 

    // ############################ Begin_Citation [4] ############################
Code that was influenced by the citation here
// ############################ End_Citation [4]  #############################

  • For Python or other languages where # is a comment: 

    ############################### Begin_Citation [4] ############################
Code that was influenced by the citation here
############################### End_Citation [4]  #############################

  • or xml and similar languages: 

    <!--########################### Begin_Citation [4] #########################-->
Code that was influenced by the citation here
<!--########################### End_Citation [4]  ##########################-->

Cross-referencing is required whenever a source has direct influence on part of the code you wrote that is specific to the problem you are trying to solve.

Citing Git Repositories and other Source Code Files

  1. This section details how git repositories and other source code can be cited properly, including those with solutions from previous students.
    • These rules are in addition to the other rules in this document
  2. It is highly discouraged for you to look at previous students' solutions or other code that directly provides solutions.
    • Sources that provide solutions directly should be viewed as an avenue of last resort and must be cited properly.
    • The homework is not the same year-to-year, often in important ways, so this is not necessarily a good idea.
  3. There must be a separate citation line for each file (or corresponding .hpp/.cpp file pair) in the remote repository that you used.
    • It is inadequate to merely cite a whole repository as a solution source: this is not specific enough.

    • Cross references must include references to particular lines in the source material, as follows: 

      // ############################ Begin_Citation [4] ############################
// file.cpp:450-300s
// ############################ End_Citation [4]  #############################
  4. It is assumed that citations for former solutions will have cross-references in your code.
    • If you are looking at another solution, there is typically a direct link between what you looked at and what you are going to be coding, even if code is not copied directly. This influence should be specifically acknowledged.
    • By citing a file of a solution and not cross-referencing, you are asserting that it only played a general role in your own work and that there is no literal, functional, or architectural (outside of the HW specifications) influence of that source on your code.
    • If there are any of the above similarities, a cross-reference is required.

AI Tools

There are additional rules for AI tools:

  1. If your use of the LLM is external to your text editor (e.g., you use a website) you must provide a transcript of the conversation in your git repository and refer to it in the citation.
  2. If the LLM is built-in to your code editor and uses the context of the editor, then prior to generating the code you must commit your code and record the hash of the commit in the citations.txt.
  3. Each individual use of an LLM must be cited.
  4. Any code that has been directly influenced by a "conversation" with AI must cross-reference the particular portion of the conversation.
    • Cross references should include line numbers in the transcript file, highlighting the relevant portion
  5. Transcripts must be included in the git repository.
    • Transcripts must be included in the repository directly, so that they can be properly cross-referenced.

Example

Here is an example citations.txt: yours should follow the same format. 

Worked With: [List every person you worked with generally here.]
[1] Github Copilot. Used on 9/21/2023. Commit prior to use is 3fd56754423456434233242
[2] ChatGpt. Used on 9/22/2023. Transcript is in ./chatgpt/transcript1.txt
[3] https://stackoverflow.com/the/answer Accessed on 9/23/22
[4] John Smith [if John Smith gave you a specific idea outside of generally working with you].

And here is an example of a C++ file that used a citation 

#include<iostream>

// ############################## Begin_Citation [4] ##############################
// From ./chatgpt/transcript1.txt:450-500
int main()
{
   std::cout << "Hello ROS!" << std::endl;
   return 0;
}
// ############################## End_Citation [4]  ###############################

Author: Matthew Elwin