We prefer Rust.
We have a bunch of Bash and Python scripts that we want to replace with Rust.
For configs we like JSON and TOML, and dislike YAML.
Follow the Google TypeScript Style Guide, and apply its language-independent rules to JavaScript, with the exceptions below.
-
External names: Preserve generated names and wire-protocol keys, including viewer event names and notebook messages. Quote wire keys; alias generated imports to local camelCase or PascalCase names.
viewer.on("recording_open", (event) => { const message = { "recording_id": event.recordingId }; console.log(JSON.stringify(message)); });
-
Private members: Use
#private, despite the guide's ban: it enforces privacy for JavaScript consumers, and ouresnexttarget avoids downlevel compilation costs. Use TypeScriptprivateonly for documented runtime integration access.
Use camelCase for functions, methods, parameters, variables, fields, and module aliases, PascalCase for types and classes, and SCREAMING_SNAKE_CASE for constants.
Use interfaces for named object shapes; keep type aliases for unions, mapped types, and other types that interfaces cannot express.
Separate top-level declarations and class methods with a blank line. Group static imports at the top of the file.
Follow Google's type-only import and re-export rules: use import type or inline type imports, and export type for type-only re-exports.
These markers require explicit import/export changes to add runtime dependencies or expose runtime values.
Use the repository's Prettier configuration for formatting and oxlint configuration for linting. JavaScript and TypeScript use two-space indentation, semicolons and trailing commas.
Run these commands from rerun/ to enforce some of the rules (also done by CI):
pixi run misc-fmt— format with Prettier.pixi run misc-fmt-check— check formatting without changing files.pixi run js-lint— lint with oxlint (requires built web-viewer bindings).
relint, our custom linter, checks many of the rules below that clippy cannot.
Run pixi run relint from rerun/ or dataplatform/, and see scripts/relint/README.md for details.
unsafe code should be only used when necessary, and should be carefully scrutinized during PR reviews.
The code should never panic or crash, which means that any instance of unwrap or expect is a potential time-bomb. Even if you structured your code to make them impossible, any reader will have to read the code very carefully to prove to themselves that an unwrap won't panic. Often you can instead rewrite your code so as to avoid it. The same goes for indexing into a slice (which will panic on out-of-bounds) - it is often preferable to use .get().
For instance:
let first = if vec.is_empty() {
return;
} else {
vec[0]
};can be better written as:
let Some(first) = vec.get(0) else {
return;
};Be careful when iterating over HashSets and HashMaps, as the order is non-deterministic.
Whenever you return a list or an iterator, sort it first.
If you don't want to sort it for performance reasons, you MUST put unsorted in the name as a warning.
We log problems using our own re_log crate (which is currently a wrapper around tracing).
- An error should never happen in silence.
- Validate code invariants using
assert!ordebug_assert!. - Validate user data and return errors using
thiserror. - Attach context to errors as they bubble up the stack using
anyhow. - Log errors using
re_log::error!orre_log::error_once!. - If a problem is recoverable, use
re_log::warn!orre_log::warn_once!. - If an event is of interest to the user, log it using
re_log::info!orre_log::info_once!. - The code should only panic if there is a bug in the code.
- Never ignore an error: either pass it on, or log it.
- Handle each error exactly once. If you log it, don't pass it on. If you pass it on, don't log it.
- Put any sensitive data (like URLs, file paths etc) LAST in the error message, so that users can send us the first half and omit the sensitive half.
- Prefer returning an error to the caller over logging it and carrying on. Do fallible setup (binding a socket, opening a device) before spawning a thread, so that the failure can be returned.
- Don't
.map_err(|err| err.to_string())unless the function returnsResult<_, String>— it throws away the error type. - Don't drop an error with
.map_err(|_err| …)unless you log it or wrap it first. - Use
warn_once!/error_once!for messages that would otherwise repeat every frame. - Invalid configuration (env vars, CLI args, config files) is an error, not a silent fallback to the default.
unwrap_or(…)andunwrap_or_default()on aResultsilently drop the error: log it or propagate it, unless ignoring it is intended.- An error message says what failed, the offending value (sensitive values last, see below), and, when it can, what the user should do instead.
- Classify a failure by who caused it.
If a server logs a rejected request, it uses
DEBUGorINFO, neverERROR:ERRORis for our own failures. Only blame the client for what you validated as its fault: errors from deeper layers (storage, I/O, dependencies) may be our bugs, and misclassifying them as client errors hides them from alerting.
Strive to encode code invariants and contracts in the type system as much as possible. So if a vector cannot be empty, consider using vec1. Parse, don’t validate.
Prefer strong types over primitive ones:
url::UrlandPathBufoverString.- A newtype (
struct StreamId(u64)) over a bare integer or a type alias. - A newtype (
struct SchemaId([u8; 32])) over a bare byte array ([u8; N]) holding a hash, key, or ID. - An enum over a
boolfield or parameter (enum Screen { Setup, Chat }overshow_setup: bool). Option<Result<(), Error>>overOption<bool>.- A named struct (or
Rangef,Span, …) over a tuple. Option<NonZeroU64>over au64where0means "disabled".
If a path or file marker could silently go stale, add a debug_assert! or a test that checks it.
Some contracts cannot be enforced using the type system. In those cases you should explicitly enforce them using assert (self-documenting code) and in documentation (if it is part of a public API).
The log is for several distinct users:
- The application user
- The application programmer
- The library user
- The library programmer
We are all sharing the same log stream, so we must cooperate carefully.
The Rerun viewer will show log messages at INFO, WARNING and ERROR to the user as a toast notifications.
This is for unrecoverable problems. The application or library couldn't complete an operation.
Libraries should ideally not log ERROR, but instead return Err in a Result, but there are rare cases where returning a Result isn't possible (e.g. then doing an operation in a background task).
Application can "handle" Errors by logging them as ERROR (perhaps in addition to showing a popup, if this is a GUI app).
Use this log level whenever some data is lost, even if you continue processing other data.
Examples: failing to write a file, failing to read parts of a file.
This is for recoverable problems. The operation completed, but couldn't do exactly what it was instructed to do.
Sometimes an Err is handled by logging it as WARNING and then running some fallback code.
Warnings are also used for thing that may be an error, but it could be intended (e.g. dropping a sink before flushing it).
Examples: usage of deprecated functions, slow paths, misuse of our APIs, lossy data conversion.
If data is lost, it is an error and NOT a warning.
This is the default verbosity level. This should mostly be used only by application code to write interesting and rare things to the application user. For instance, you may perhaps log that a file was saved to specific path, or where the default configuration was read from. These things lets application users understand what the application is doing, and debug their use of the application.
This is a level you opt-in to to debug either an application or a library. These are logged when high-level operations are performed (e.g. texture creation). If it is likely going to be logged each frame, move it to TRACE instead.
This is the last-resort log level, and mostly for debugging libraries or the use of libraries. Here any and all spam goes, logging low-level operations.
The distinction between DEBUG and TRACE is the least clear. Here we use a rule of thumb: if it generates a lot of continuous logging (e.g. each frame), it should go to TRACE.
Requests, files, and anything else from outside the process can be malicious or degenerate.
- Bound every size or count that the input controls, e.g. cap list lengths in requests.
- Use
saturating_*orchecked_*arithmetic on sizes and offsets that the input controls. - Check that responses built from the input stay within transport limits (e.g. the gRPC message size).
- Don't check for a file and then act on it (TOCTOU): do the operation and handle the error.
For reporting warnings (or partial-failures) up the call-stack, we like the reporter pattern:
struct WarningReporter {
reports: Mutex<Vec<Warning>>,
}
pub fn thing_that_can_produce_warnings(reporter: &WarningReporter, other_paramets: …) -> Result<…> {}The important parts of this pattern is:
- Accumulate warnings and then continue
- Interior mutability, so we can share the reporter with child threads
- Structured warnings (more than just a String!)
We use this for partial failures, when something went wrong but we don't want to abort, but instead continue with best-effort.
We prefer this pattern complex return types ((Vec<Warning>, Object)), because the reporter pattern is often a lot less syntactically noisy in Rust.
It is also easy to ignore part of a return-type, but it is harder to ignore an extra parameter. Thus we force ourselves to handle warnings.
This allows code like this:
fn some_panel_ui(ctx: &ViewerContext, ui: &mut Ui) {
let reporter = WarningReporter::default();
let object = do_some_query(&reporter, …)?;
object.ui(ui);
if reporter.is_missing_chunks() {
ui.loading_indicator("Doing query");
}
if !reporter.warnings().is_empty() {
warnings_ui(reporter.warnings());
}
}We use thiserror for errors in our libraries, and anyhow for type-erased errors in applications.
Don't add anyhow to a library crate, not even for a one-off error: add a variant to the crate's error type instead.
For faster hashing, we use ahash (ahash::HashMap, …).
When the hashmap key is high-entropy we use nohash-hasher (nohash_hasher::IntMap and IntSet).
This includes any key that is itself a hash, e.g. EntityPath, ComponentDescriptor, InternedString, and other types that implement nohash_hasher::IsEnabled.
Use re_format to format numbers, durations, and sizes for humans, e.g. format_uint, format_f64, format_bytes, and DurationFormatOptions, rather than format!("{x}").
That way we get the same thousands separators, minus sign, and units everywhere.
We follow the Rust API Guidelines.
We use rust fmt with default settings.
We have blank lines before functions, types, impl blocks, and docstrings.
We format comments // Like this, and //not like this.
When importing a trait to use its trait methods, do this: use Trait as _;. That lets the reader know why you imported it, even though it seems unused.
When intentionally ignoring a Result, prefer foo().ok(); over let _ = foo();. The former shows what is happening, and will fail to compile if foo:s return type ever changes.
We group and order imports (use statements) by std, other crates, and lastly own crate and super. This corresponds to StdExternalCrate.
We group our use statements by module, e.g. crate_name::module::{a, b, c}. This is a compromise, being rather terse while still avoiding excessive merge conflicts. See the cargofmt docs for details.
Both of these are nightly-only rustfmt options (group_imports and imports_granularity), so the stable cargo fmt that CI runs does not enforce them.
We re-apply them now and then with the nightly-fmt skill (.claude/skills/nightly-fmt/SKILL.md), run as nightly-fmt.sh --imports.
Use the destructor syntax (let Self { a, b, c} = self;) whenever you're accessing most of (or all) of the fields of a struct.
This also makes the compiler tell you when a new field is added that you may have forgotten about.
If you use a type or function more than twice in a file, add a use for it at the top of the file instead of spelling out its full path each time.
Put types and constants at the top of the file, before the functions that use them.
Keep hand-written lists sorted alphabetically, unless the order carries meaning.
This includes enum variants, match arms, Cargo features, clippy.toml entries, .gitattributes lines, and tables in docs.
Prefer cfg_select! over pairs of #[cfg(…)]/#[cfg(not(…))] blocks.
When every branch compiles without warnings on all targets, prefer a plain if cfg!(…) { … } else { … } over cfg_select!.
For UI, prefer a runtime check (e.g. a disabled button on web) over compile-time #[cfg].
Add re_tracing::profile_function!() (or profile_scope!) to functions that may be slow, e.g. I/O, encoding and decoding, opening or closing devices, and large loops.
Don't await independent I/O one at a time in a loop: run it concurrently, with a concurrency limit.
Don't issue one query or request per item when one call can fetch them all.
Don't wrap code in a closure that is called immediately, and don't extract a helper that is only called once unless it names a concept.
Avoid catch-all _ => arms when matching on our own enums, so that the compiler flags every match that needs updating when a variant is added.
Prefer if let … else over a match … pattern => …, _ => … when possible.
Don't negate a parenthesized boolean expression: write !a || !b instead of !(a && b).
Every new timeout, size limit, or threshold needs a reason: say where the number comes from, or reuse an existing constant. Refer to metadata keys and column names through their constants, never through a string literal.
- Prefer constructors and associated functions over free functions.
- Put general or context parameters first and specific ones last, e.g.
fn entity_ui(ctx: &ViewerContext, ui: &mut Ui, entity_path: &EntityPath). - Avoid global state (
static FOO: LazyLock<…>); let the caller own it. - Instead of
fn should_do_x(x) -> bool+fn do_x(x), write a singlefn do_x(x) -> Option<…>. - Keep items private by default, and make only the intended API
pub. Don't make a fieldpubif it also has a setter. - Keep
lib.rsandmod.rsshort: mostlymoddeclarations andpub usestatements that list what the crate exports. Small items like constants are fine there too; move functions and types with real logic into their own modules. - Don't add traits, public methods, or hooks to production code only so that tests can use them.
- Don't add code "for later", or backwards compatibility that nothing needs. Nothing needs compatibility with a feature that has not shipped or been announced.
- Don't add an abstraction (trait, builder, env var, config knob) with a single implementation or value, unless it encodes an invariant the compiler then checks.
- Before writing a helper, look for an existing one in this repo or in a dependency we maintain (egui, emath, quiver, …). If it is missing there, add it upstream instead of working around it locally.
Every crate-level public item, and every public field such structs, should have a docstring.
Document behavior, not implementation: what it does, units, defaults, and what happens in edge cases (missing, empty, already exists, …).
Explain domain terms for readers who are not experts in that domain.
If something has several names (e.g. application_id is the dataset id), list them.
Start a multi-line docstring with a one-line summary, followed by an empty line.
Put the docstring before any #[derive(…)] attributes.
Comments must add durable value: explain non-obvious invariants, contracts, performance constraints, or caller obligations. Don't write comments that justify a change to the reviewer, narrate what the next line does, or describe history ("no longer", "deliberately", "being phased out"). A comment describes the code it is attached to: don't describe what other code does ("see the module docs", "same as the X branch"), or what may happen in the future. Document a fact once, where it is true, and link to it from elsewhere.
A wrong comment is worse than no comment: after changing or renaming code, check that the comments around it are still true.
When you must remember to do something before merging a PR, write TODO or FIXME in any file. The CI will not be green until you either remove them or rewrite them as TODO(yourname).
For work that is left for a later PR, prefer linking an issue, e.g. TODO(rerun-io/rerun#1234) or TODO(RR-1234), so it doesn't get lost.
Every temporary workaround and every deprecation gets such a TODO linking the issue for its removal.
Keep the TODO text short and high-level; the details go in the issue.
You can also use the todo()! macro during development, but again it won't pass CI until you rewrite it as todo!("more details"). Of course, we should try to avoid todo! macros in our code.
Use debug-formatting ({:?}) when logging strings in logs and error messages. This will surround the string with quotes and escape newlines, tabs, etc. For instance: re_log::warn!("Unknown key: {key:?}");.
Use {:#} or re_error::format(err) when displaying an error - NOT Debug/{:?}.
Name error variables err, not e: Err(err) => …, .map_err(|err| …).
Inline simple variables in format strings: format!("{name}"), not format!("{}", name).
Derive egui ids from the parent Ui with ui.make_persistent_id(…), so that two instances of the same widget don't collide.
Hash a tuple rather than building an id with format!: ui.make_persistent_id(("plot_legend", view_id)).
We make extensive use of snapshot testing. To work around non-deterministic values, such as TUIDs (time-prefixed unique IDs), many types (should) offer std::fmt::Display implementations with redactions that can be access via an overloaded - formatting option:
println!("{:-}, value"); // The `-` option stands for redaction.Look for f.sign_minus() in the code for where we handle this.
Arguments that every caller passes are positional; all others are keyword-only (kw-args).
- Bad:
def serve(ip: str, port: int = 80, token: str | None = None, timeout_sec: int = 8) - Bad:
def serve(*, ip: str, port: int = 80, token: str | None = None, timeout_sec: int = 8) - Good:
def serve(ip: str, *, port: int = 80, token: str | None = None, timeout_sec: int = 8)
The * forces the use of kw-args for everything following it.
Flags and modes (bool, Literal[…]) always go after the *, so call sites read overwrite=True instead of a bare True.
kw-args have two big benefits:
First, they make future API changes a lot easier. We can add or remove arguments without breaking the API (just log deprecation notices).
Secondly, named arguments makes the caller code a lot more readable.
Do not make a required argument keyword-only, unless a positional call would be ambiguous: several required arguments a caller could swap (set_default_size(*, width, height), stage(source, *, key)), or a choice between keyword alternatives (set_time(timeline, sequence=…)).
Otherwise every caller pays for it.
The argument nearly every caller passes may stay positional even with a default, as in get_dataset(name: str | None = None, *, id: EntryId | str | None = None).
We use clang-format to enforce most style choices (see .clang-format).
Always use const unless you plan on mutating it, with the exception of function parameters (because that is just too much noise).
We use const auto x = … for declaration because that gives symmetric code for normal constructors and static constructors:
const auto foo = SomeClass{…};
const auto bar = SomeClass::new_xyzw(…);We prefer {} for constructors (Foo{…} instead of Foo(…)), though there are exceptions (std::vector{2, 3} is different from std::vector(2, 3)).
Prefer using Type = …; over typedef … Type;.
We prefix private member variables with a _:
class Thing {
public:
…
void set_value(uint32_t value) {
_value = value;
}
private:
uint32_t _value;
}Public member variables has no prefix.
When necessary use a _ suffix on parameter names to avoid name conflicts:
struct Thing {
uint32_t value;
void set_value(uint32_t value_) {
value = value_;
}
}We use C++ constructors when it is unambiguous, but prefer named static constructors otherwise.
Like Rust, we use the from_ prefix for static constructors, and the with_ prefix for builder methods.
class Rect {
// We can't just overload normal constructors for these:
static Rect from_min_max(Vec2 min, Vec2 max) { … }
static Rect from_center_size(Vec2 center, Vec2 size) { … }
Rect with_color(Color color) && {
_color = color;
return std::move(*this); // `*this` is always an lvalue, so we have to move it to avoid a copy.
}
}Constants & enum values have PascalCase names.
When possible, use constexpr for (global & struct/class scoped) constants.
Whenever possible we use std::string_view to pass strings.
To accommodate for this and other languages, strings on the C interface are almost never expected to be null-terminated and are always passed along with a byte length using rr_string.
We don't add inline before class/struct member functions if they are inlined in the class/struct definition.
Preprocessor directives/macros are usually prefixed with RR_
Include what you use: if you use std::vector, then include <vector> - don't depend on a transitive include.
We prefer the "data, length" parameter order, e.g. void foo(const void* data, size_t len) or void image(const f32* data, Resolution resolution).
We prefer snake_case to kebab-case for most things (e.g. crate names, crate features, …). snake_case is a valid identifier in almost any programming language, while kebab-case is not. This means one can use the same snake_case identifier everywhere, and not think about whether it needs to be written as snake_case in some circumstances.
When in doubt, be explicit. BAD: id. GOOD: msg_id.
Be terse when it doesn't hurt readability. BAD: message_identifier. GOOD: msg_id.
Avoid negations in names. A lot of people struggle with double negations, so things like non_blocking = false and if !non_blocking { … } can become a source of confusion and will slow down most readers. So prefer connected over disconnected, initialized over uninitialized etc.
Name things for what they are, not for what they are used for.
Don't repeat the type in the name: age, not age_integer.
Use one name for one concept, everywhere. Before naming a new public item, look at its siblings (other methods on the type, the same concept in the other SDKs or the proto) and reuse their nouns and verbs. Don't coin a new term for something that already has a name.
For UI functions (functions taking an &mut egui::Ui argument), we use the name ui or _ui suffix, e.g. blueprint_ui(…) or blueprint.ui(…).
In weak/stringly typed situations, be extra careful. This includes Python, Bash, and CLI args.
Avoid vague names like "address". Prefer one of:
ipip_porturlemail- …
- When in doubt, be explicit (
duration_secs: f32is better thanduration: f32) - All things being equal, prefer SI base units (seconds over milliseconds, Hz over RPM, etc)
- When precision matters, prefer
nanos: i64oversecs: f64 - Store angles in radians (but you may print/display them as degrees)
Follow the conventions set by Rust stdlib:
secsinstead ofsecondsmillisinstead ofmsormillisecondsmicrosinstead ofusormicrosecondsnanosinstead ofnsornanoseconds
Points, vectors, rays etc all live in different spaces. Whenever there is room for ambiguity, we explicitly state which space something is in, e.g. with ray_in_world.
Here are some of our standard spaces:
ui: coordinate system used byegui, measured in logical pixels ("points"), with origin in the top leftimage: image pixel coordinates, possibly with an addedz=depthspace: a user-defined space where they log stuff intoworld: the common coordinate system of a 3D scene, usually same asspaceview: X=right, Y=down, Z=back, origin = center of screen
We use column vectors, which means matrix multiplication is done as M * v, i.e. we read all matrix/vector operations right-to-left. We therefore name all transform matrices as foo_from_bar, for instance:
let point_in_world = world_from_view * point_in_view;This means the name of the space matches up nicely, e.g.:
let projection_from_object = projection_from_view * view_from_world * world_from_object;See https://www.sebastiansylvan.com/post/matrix_naming_convention/ for motivation.
For consistency, we use the same naming convention for other non-matrix transforms too. For instance, functions: let screen = screen_from_world(world);.
Vectors are directions with magnitudes. Points are positions.