Code Standards

// Good
const MAX_BUFFER_SIZE: usize = 64;

pub struct ImeEngine {
    current_method: InputMethod,
}

pub fn process_keystroke(key: u16) -> Result {
    // ...
}

// Bad
const maxBufferSize: usize = 64;  // Should be SCREAMING_SNAKE_CASE
pub struct ime_engine { }          // Should be CamelCase
pub fn ProcessKeystroke() { }      // Should be snake_case

//! Module-level documentation explaining purpose

// === Imports ===
use crate::data::keys;
use std::collections::HashMap;

// === Constants ===
pub const MAX_BUFFER: usize = 64;
const DEFAULT_METHOD: u8 = 0;

// === Type Definitions ===
pub struct MyStruct {
    field: Type,
}

pub enum MyEnum {
    Variant1,
    Variant2,
}

// === Public Functions ===
pub fn public_function() {
    // Implementation
}

// === Private Implementation ===
fn private_helper() {
    // Implementation
}

// === Tests ===
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_something() {
        // Test implementation
    }
}

[dependencies]
# No external dependencies!

[dev-dependencies]
rstest = "0.18"
serial_test = "3.0"

/// Process a Vietnamese keystroke through the IME engine.
///
/// # Arguments
/// * `key` - macOS virtual keycode (0-127)
/// * `caps` - true if Shift or CapsLock is pressed
/// * `ctrl` - true if Control is pressed
///
/// # Returns
/// Pointer to Result struct containing:
/// - `action`: Type of action to perform (0=none, 1=replace, 2=append)
/// - `backspace`: Number of characters to delete
/// - `count`: Number of output characters
/// - `chars`: Output character array
///
/// # Safety
/// The caller must free the returned pointer using `ime_free()`.
///
/// # Example
/// ```c
/// ImeResult* result = ime_key(keys::A, false, false);
/// if (result && result->action == 1) {
///     // Process result->backspace and result->chars
/// }
/// ime_free(result);
/// ```
#[no_mangle]
pub extern "C" fn ime_key(key: u16, caps: bool, ctrl: bool) -> *mut Result {
    // Implementation
}

// Good: Safe error handling
#[no_mangle]
pub extern "C" fn ime_process(input: *const c_char) -> *mut Result {
    if input.is_null() {
        return ptr::null_mut();  // Safe fallback
    }
    // Process...
}

// Bad: Can panic
pub extern "C" fn ime_process(input: *const c_char) -> *mut Result {
    let s = unsafe { CStr::from_ptr(input) };
    s.to_str().unwrap()  // ❌ Can panic!
}

#[cfg(test)]
mod tests {
    use super::*;
    use rstest::rstest;

    // Simple test
    #[test]
    fn test_basic_conversion() {
        let result = convert_tone('a', Tone::Sac);
        assert_eq!(result, 'á');
    }

    // Parameterized test
    #[rstest]
    #[case('a', Tone::Sac, 'á')]
    #[case('a', Tone::Huyen, 'à')]
    #[case('e', Tone::Hoi, 'ẻ')]
    fn test_tone_conversion(
        #[case] base: char,
        #[case] tone: Tone,
        #[case] expected: char
    ) {
        assert_eq!(convert_tone(base, tone), expected);
    }
}

make test                          # All tests
cd core && cargo test              # Core tests only
cargo test -- --nocapture          # With output
cargo test test_name               # Specific test

// MARK: - Imports
import Foundation
import AppKit

// MARK: - Constants
let kDebugLogPath = "/tmp/gonhanh_debug.log"

// MARK: - Type Definitions
class InputMethodManager {
    // MARK: - Properties
    private var isEnabled: Bool
    private var currentMethod: InputMethod

    // MARK: - Lifecycle
    init() {
        self.isEnabled = false
        self.currentMethod = .telex
    }

    // MARK: - Public Methods
    func toggle() {
        isEnabled.toggle()
    }

    // MARK: - Private Methods
    private func updateStatus() {
        // Implementation
    }
}

// MARK: - Extensions
extension InputMethodManager: CustomStringConvertible {
    var description: String {
        return "InputMethod(enabled: \(isEnabled))"
    }
}

--swiftversion 5.9
--exclude build
--disable wrapPropertyBodies

make format
# or
swiftformat platforms/macos --quiet

// Good: Proper error handling
if let result = ime_key(key: keyCode, caps: capsLock, ctrl: false) {
    defer { ime_free(result) }
    processResult(result.pointee)
} else {
    NSLog("IME processing failed for key: \(keyCode)")
}

// Bad: Force unwrapping
let result = ime_key(...)!
processResult(result.pointee)  // ❌ Crashes if nil

// UI updates on main thread
DispatchQueue.main.async {
    self.statusItem.title = newTitle
}

// Background work
DispatchQueue.global(qos: .userInitiated).async {
    let data = self.processData()
    DispatchQueue.main.async {
        self.updateUI(with: data)
    }
}

// ✅ Correct: Use defer for cleanup
guard let resultPtr = ime_key(keyCode, caps, ctrl) else {
    return
}
defer { ime_free(resultPtr) }  // Guaranteed cleanup

let result = resultPtr.pointee
processResult(result)

// ❌ Wrong: Manual cleanup (easy to forget)
let resultPtr = ime_key(keyCode, caps, ctrl)
processResult(resultPtr!.pointee)
ime_free(resultPtr)  // What if processResult throws?

// Import with exact Rust signature
@_silgen_name("ime_key")
func ime_key(
    _ key: UInt16,
    _ caps: Bool,
    _ ctrl: Bool
) -> UnsafeMutablePointer<ImeResult>?

@_silgen_name("ime_free")
func ime_free(_ ptr: UnsafeMutablePointer<ImeResult>?)

<type>(<scope>): <subject>

<body>

<footer>

MAJOR.MINOR.PATCH