conventions.md

Rust Coding Conventions

String Interpolation

For format!, println!, info!, debug!, and similar macros, either for normal display like {} or debug display like {:?}, use the following:

Correct Usage:

• ALWAYS use direct variable names when they match the placeholder name:

  let name = "John";
  println!("Hello {name}");  // GOOD - Direct use of variable name in placeholder
  
  // This also applies to all logging macros
  let endpoint = "users";
  debug!("Processing request for {endpoint}");  // GOOD

• ONLY use named parameters when using a property or method:

  println!("Count: {count}", count = items.len());  // GOOD - Method call needs named parameter

• ALWAYS use placeholder names that match the variable names. NEVER create temporary variables just to match placeholder names:

  // GOOD - Placeholder name matches variable name
  println!("Checked {files_checked} files");
  
  // GOOD - Named parameter for method call
  println!("Found {errors_count} errors", errors_count = errors.len());
  
  // BAD - Don't create temporary variables to match placeholders
  let files = files_checked; // DON'T do this
  let errors = errors.len(); // DON'T do this
  println!("Checked {files} files, found {errors} errors");

Incorrect Usage:

• Don't use positional arguments:

  let name = "John";
  println!("Hello {}", name);  // BAD - No named placeholder

• Don't use redundant named parameters when the variable name matches:

  let name = "John";
  println!("Hello {name}", name = name);  // BAD - Redundant, just use "{name}"

• Don't use different names unnecessarily:

  let name = "John";
  println!("Hello {user}", user = name);  // BAD - Not property or method, just use "{name}" directly

Error Handling

Correct Usage:

• ALWAYS use anyhow for error handling, particularly bail! and ensure!:

  // For conditional checks
  ensure!(condition, "Error message with {value}");
  
  // For early returns with errors
  bail!("Failed with error: {error_message}");
  
  // For adding context to errors
  let result = some_operation.context("Operation failed")?;

Incorrect Usage:

• NEVER use unwrap() or panic!:

  // BAD - Will crash on None:
  let result = optional_value.unwrap();
  
  // BAD - Will crash on Err:
  let data = fallible_operation().unwrap();
  
  // BAD - Explicit panic:
  panic!("This failed");

• Avoid using .ok() or .expect() to silently ignore errors:

  // BAD - Silently ignores errors:
  std::fs::remove_file(path).ok();
  
  // BETTER - Log the error but continue:
  if let Err(e) = std::fs::remove_file(path) {
      debug!("Failed to remove file: {e}");
  }