C++ Beginner · Lesson 04 of 22

Comments, formatting and naming

// and /* */ comments, readable layout, and naming conventions used in ROS 2.

Estimated time · 30–45 min

Learning goals

What you will understand

Explain comments, formatting and naming in your own words
Use it in a small robotics example
Verify the result instead of assuming it worked

Understand the idea first

The mental model

A comment is text the compiler ignores. // comments to the end of the line; /* ... */ can span lines. Good comments explain why something is done, not what the syntax already says.

Consistent formatting makes bugs visible. ROS 2 code uses snake_case for variables and functions, PascalCase for types, and a trailing underscore for member variables. Use a formatter such as clang-format so style is never a debate.

Guided lesson

Work through these steps

1.
Read the comments, formatting and naming example and identify what each line owns or changes.
2.
Create a small source file, compile with -std=c++17 and warnings enabled, and run it.
3.
Change one input, predict the result before running, then compare the output.
4.
Record one compiler or runtime error and explain the correction in your own words.

Worked example

Read it before you run it

// Maximum joint speed the controller may command, in rad/s.
// A comment says why the number exists, not what the type is.
constexpr double max_joint_speed = 1.2;
// A compile-time constant in snake_case.
struct JointState {
// A type name in PascalCase.
  double position_rad{0.0};
// A member with its unit in the name so it cannot be misread.
};
// A struct ends with a semicolon.
/* A block comment can span several lines. */
// This form is useful for a longer explanation or to disable a block temporarily.

What the example is doing

1.Read declarations from right to left: identify each value's type, name, and initial value.
2.Follow the data through each expression before considering syntax shortcuts.
3.Compile with warnings enabled; a clean build is part of the result, not an optional polish step.

Watch it run · Values in memory

See what this code does

The terminal types this lesson's practice solution and runs it. The scene shows the kind of robot behaviour that code drives. It plays by itself and loops.

Practice code

Now type it yourself

Copy the starter into practice.cpp and replace every TODO with your own code. Build and run it: g++ -std=c++17 -Wall -Wextra -Wpedantic practice.cpp -o practice -pthread && ./practice

#include <iostream>

constexpr double pi = 3.14159265358979;
constexpr double max_joint_speed_rad_s = 1.2;  // unit in the name: radians per second

// TODO: write rad_to_deg(double rad) returning rad * 180.0 / pi

int main() {
  std::cout << rad_to_deg(max_joint_speed_rad_s) << " deg/s\n";
  return 0;
}

Expected output

68.7549 deg/s

Stuck? Show the full solution (try it yourself first)

#include <iostream>

constexpr double pi = 3.14159265358979;
constexpr double max_joint_speed_rad_s = 1.2;  // unit in the name: radians per second

constexpr double rad_to_deg(double rad) { return rad * 180.0 / pi; }

int main() {
  std::cout << rad_to_deg(max_joint_speed_rad_s) << " deg/s\n";
  return 0;
}

Expected result

How you know it worked

After adding the shown fragment to the guided exercise with its listed headers and surrounding program, the finished program builds with -Wall -Wextra -Wpedantic.
Changing the stated input produces the result you predicted.

Practical exercise

Apply the lesson

Take a 15-line program you wrote earlier, rename every variable to snake_case with units where useful, add a why-comment for each constant, and run clang-format on it.

Before you continue

The program builds with -std=c++17 and no warnings
You can explain the key rule without reading the example
The normal and edge cases both have recorded results

If something goes wrong

The compiler reports that a name or type is unknown.

Start at the first error. Check spelling, required #include lines, and whether the declaration appears before use.

The program runs but the value is wrong.

Print the inputs and intermediate values, then check conversions, units, and collection order.