write-code

Write Code

Rust code conventions for Syncpack.

Style

• Functional style: pipelines over loops
• Avoid ? chains: use .and_then(), .map(), .or_else()
• Descriptive names: clarity over brevity
• Named placeholders: println!("{var}") not println!("{}", var)
• British English: "behaviour" not "behavior", "organised" not "organized"

Imports

Single use statement with grouped braces:

use {
  crate::{cli::Cli, config::Config},
  log::{debug, error},
  std::{process::exit, sync::Arc},
};

Rules:

• Never use super:: — always crate:: for internal imports
• Group: crate::, external crates, std::
• Alphabetise within groups

File Organisation

NEVER use #[cfg(test)] modules inside implementation files.

Quality

• Functions <50 lines, commands 100-300 lines
• Zero warnings (except during TDD red phase)
• Run just format before committing

Comments

Forbidden

• //! module docs — collect implementation history and rot
• Phase/F-N labels — // Phase v4-2, // F16:, banner headers like // ---------- Phase v4-3 RED ----------
• History refs — Migrated from, carry-over, Mirrors v3, replaces the v3, previously inside X, reserved for future
• Issue/PR refs — Reproduces issue #239, GitHub issue #206. Plans rot; the code is the truth
• Banner separators — // ---------- Free functions: yaml ops ----------. Use module structure or let the file speak for itself
• Test scenario labels — don't write // Windows-style backslashes above a test input. Use a descriptive variable binding (let windows_backslashes = [...]) instead
• Name-restating field docs — /// A unique identifier for this instance, /// The dependency name, /// The instance id. The field name already says it
• Step numbering inside functions — // 1. ..., // 2. .... Drop the numbers; keep the WHY if it's non-obvious

Allowed

• @TODO markers — future plans worth tracking inline
• /// doc comments for non-obvious detail: None/Err semantics, side effects, invariants, distinctions between similar fields (e.g. is_local_dependency vs is_local_instance)
• // inline comments when WHY is non-obvious: hidden constraints, ordering invariants ("SnappedTo groups must be visited last"), workarounds for surprising library behaviour, "must not poison X" cautions

Default

No comments. Add one only when the WHY is non-obvious to a fresh reader.

Patterns

Iterating Instances

ctx.version_groups.iter().for_each(|group| {
    group.get_sorted_dependencies(&ctx.config.cli.sort).for_each(|dependency| {
        dependency.get_sorted_instances()
            .filter(|instance| instance.is_invalid())
            .for_each(|instance| { /* process */ });
    });
});

Error Handling

Prefer combinators over ?:

// Good
path.parent()
    .and_then(|p| p.to_str())
    .map(|s| s.to_string())
    .unwrap_or_default()

// Avoid
let parent = path.parent()?;
let str = parent.to_str()?;
Ok(str.to_string())

State Mutation

let mut state = instance.state.borrow_mut();
if !state.is_invalid() {
    *state = InstanceState::fixable(SomeVariant);
}