|
| 1 | +# Claude Code Style Guide for MinIO Rust SDK |
| 2 | + |
| 3 | +- Only provide actionable feedback. |
| 4 | +- Exclude code style comments on generated files. These will have a header signifying that. |
| 5 | +- Use github markdown folded sections for all items. |
| 6 | +- Do not use emojis. |
| 7 | +- Do not add a "feel good" section. |
| 8 | + |
| 9 | +## Copyright Header |
| 10 | + |
| 11 | +All source files that haven't been generated MUST include the following copyright header: |
| 12 | + |
| 13 | +```rust |
| 14 | +// MinIO Rust Library for Amazon S3 Compatible Cloud Storage |
| 15 | +// Copyright 20?? MinIO, Inc. |
| 16 | +// |
| 17 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 18 | +// you may not use this file except in compliance with the License. |
| 19 | +// You may obtain a copy of the License at |
| 20 | +// |
| 21 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 22 | +// |
| 23 | +// Unless required by applicable law or agreed to in writing, software |
| 24 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 25 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 26 | +// See the License for the specific language governing permissions and |
| 27 | +// limitations under the License. |
| 28 | +``` |
| 29 | + |
| 30 | +## Code Style Guidelines |
| 31 | + |
| 32 | +### Ignore files |
| 33 | +- Ignore files from processing mentioned under '.gitignore' |
| 34 | + |
| 35 | +### Comments |
| 36 | +- **NO redundant comments** - Code should be self-documenting |
| 37 | +- Avoid obvious comments like `// Set x to 5` for `x := 5` |
| 38 | +- Only add comments when they explain WHY, not WHAT |
| 39 | +- Document complex algorithms or non-obvious business logic |
| 40 | + |
| 41 | +## Critical Code Patterns |
| 42 | + |
| 43 | +### Builder Pattern |
| 44 | +All S3 API requests MUST use the builder pattern, with the following documentation but then for the appropriate API |
| 45 | + |
| 46 | +```rust |
| 47 | +/// Argument builder for the [`AppendObject`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-objects-append.html) S3 API operation. |
| 48 | +/// |
| 49 | +/// This struct constructs the parameters required for the [`Client::append_object`](crate::s3::client::Client::append_object) method. |
| 50 | +``` |
| 51 | + |
| 52 | +**Key Requirements:** |
| 53 | +1. The aws docs url must exist. |
| 54 | + |
| 55 | +### Error Handling Pattern |
| 56 | +All Rust SDK methods should follow consistent error handling patterns: |
| 57 | + |
| 58 | +```rust |
| 59 | +impl Client { |
| 60 | + pub async fn operation_name(&self, args: &OperationArgs) -> Result<OperationResponse, Error> { |
| 61 | + // Validate inputs early |
| 62 | + args.validate()?; |
| 63 | + |
| 64 | + // Build request |
| 65 | + let request = self.build_request(args)?; |
| 66 | + |
| 67 | + // Execute with proper error propagation |
| 68 | + let response = self.execute(request).await?; |
| 69 | + |
| 70 | + // Parse and return |
| 71 | + OperationResponse::from_response(response) |
| 72 | + } |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +## Code Quality Principles |
| 77 | + |
| 78 | +### Why Code Quality Standards Are Mandatory |
| 79 | + |
| 80 | +Code quality standards are **critical business requirements** for MinIO Rust SDK: |
| 81 | + |
| 82 | +1. **Enterprise Data Safety**: A single bug can corrupt terabytes of customer data across distributed systems |
| 83 | +2. **Code Efficiency**: MinIO Rust SDK code must be efficient and performant |
| 84 | +3. **Scalability**: MinIO Rust SDK must be able to handle thousands of concurrent requests |
| 85 | +4. **High Availability**: Systems must handle failures gracefully - unpredictable code creates cascading failures |
| 86 | +5. **Developer Velocity**: New team members must understand complex distributed systems quickly and safely |
| 87 | + |
| 88 | +### Predictable Code Requirements |
| 89 | + |
| 90 | +Code must exhibit **deterministic behavior** to ensure system reliability: |
| 91 | + |
| 92 | +1. **Managed State**: Use Arc<Mutex<>> or Arc<RwLock<>> for shared state that needs thread-safe access across async operations |
| 93 | +2. **Explicit Dependencies**: Business logic dependencies should be passed as parameters or dependency injection |
| 94 | +3. **Deterministic Operations**: Avoid time-dependent logic, random values, or platform-specific behavior in core paths |
| 95 | +4. **Consistent Error Handling**: Same error conditions must always produce identical error responses |
| 96 | +5. **Idempotent Operations**: Operations should be safely repeatable without unintended side effects |
| 97 | + |
| 98 | +### Readability Standards |
| 99 | + |
| 100 | +Complex distributed systems code must remain **human-readable**: |
| 101 | + |
| 102 | +1. **Self-Documenting Code**: Function and variable names should clearly express business intent |
| 103 | +2. **Consistent Patterns**: Follow established patterns (HTTP handlers, error handling, logging) |
| 104 | +3. **Logical Flow**: Code should read as a clear narrative from top to bottom |
| 105 | +4. **Minimal Cognitive Load**: Each function should have a single, well-defined responsibility |
| 106 | +5. **Clear Abstractions**: Break complex operations into well-named, focused helper functions |
| 107 | + |
| 108 | +### Separation of Concerns |
| 109 | + |
| 110 | +**Architectural layers must maintain clear boundaries**: |
| 111 | + |
| 112 | +1. **Handler Layer**: HTTP request/response processing, input validation, context creation |
| 113 | +2. **Service Layer**: Business logic orchestration, data transformation |
| 114 | +3. **Storage Layer**: Data persistence, replication, consistency management |
| 115 | +4. **Utility Layer**: Reusable helpers with no business logic dependencies |
| 116 | +5. **Shared State Coordination**: Use thread-safe primitives (Arc, Mutex, RwLock) for components needing consistent views |
| 117 | + |
| 118 | +### Functions and Methods |
| 119 | +- Keep functions focused on a single responsibility |
| 120 | +- Use descriptive names that clearly indicate purpose and business intent |
| 121 | +- Prefer early returns to reduce nesting complexity |
| 122 | +- Error handling should be immediate and explicit |
| 123 | +- **Function length guideline**: Most functions should be under 100 lines; handlers may be longer due to validation logic |
| 124 | +- **Parameter limits**: Prefer structs over long parameter lists for better maintainability |
| 125 | + |
| 126 | +### Variables |
| 127 | +- Use meaningful variable names that reflect business concepts |
| 128 | +- Variable names should reflect usage frequency: frequent variables can be shorter |
| 129 | +- Constants should follow Rust patterns |
| 130 | +- Global variables should be clearly identified and documented for their system-wide purpose |
| 131 | + |
| 132 | +### Developer Documentation |
| 133 | + |
| 134 | +**All significant features must include developer documentation** in the `docs/` directory: |
| 135 | + |
| 136 | +1. **API Documentation**: New endpoints must have usage examples in `docs/` |
| 137 | +2. **Architecture Decisions**: Complex algorithms or design patterns should be documented |
| 138 | +3. **Configuration Changes**: New config options must be documented with examples |
| 139 | +4. **Integration Guides**: External system integrations need clear setup instructions |
| 140 | +5. **Future Developer Context**: Document WHY decisions were made, not just WHAT was implemented |
| 141 | + |
| 142 | +## Testing Requirements |
| 143 | + |
| 144 | +### Why Unit Tests Are Mandatory |
| 145 | + |
| 146 | +Unit tests are **non-negotiable** in this project for critical business reasons: |
| 147 | + |
| 148 | +1. **Data Integrity**: MinIO Rust SDK handles enterprise-critical data. A single bug can cause data loss affecting thousands of users |
| 149 | +2. **Security Compliance**: Financial and healthcare customers require verifiable code quality. Tests provide audit trails |
| 150 | +3. **Multi-tenant Reliability**: One customer's workload cannot impact another's. Tests ensure proper isolation |
| 151 | +4. **Performance SLAs**: Enterprise customers have strict performance requirements. Tests validate behavior under load |
| 152 | +5. **API Stability**: Breaking changes can affect thousands of applications. Tests prevent regressions |
| 153 | +6. **Distributed System Complexity**: Complex interactions between storage nodes require comprehensive testing |
| 154 | + |
| 155 | +### Mandatory Unit Tests |
| 156 | +**EVERY implementation MUST include unit tests** without being explicitly asked. Follow these patterns: |
| 157 | + |
| 158 | +1. Test functions must use `#[test]` or `#[tokio::test]` attributes |
| 159 | +2. Use parameterized tests or loop through test cases for multiple scenarios |
| 160 | +3. Cover both success and error cases, including edge conditions |
| 161 | +4. Mock external dependencies appropriately |
| 162 | +5. **Test coverage guideline**: Aim for comprehensive coverage of new code paths |
| 163 | +6. Include negative tests for error conditions and boundary cases |
| 164 | +7. Add benchmarks for performance-critical code paths |
| 165 | + |
| 166 | +## Improvement Suggestions |
| 167 | + |
| 168 | +Claude will periodically analyze the codebase and suggest: |
| 169 | +- Missing test coverage areas |
| 170 | +- Performance optimizations |
| 171 | +- Code refactoring opportunities |
| 172 | +- Security improvements |
| 173 | +- Documentation gaps |
| 174 | + |
| 175 | +## Testing Commands |
| 176 | + |
| 177 | +### Pre-commit Checklist |
| 178 | + |
| 179 | +Before any code changes: |
| 180 | +1. ✅ Run `cargo fmt --all` to check and fix code formatting |
| 181 | +2. ✅ Run `cargo test` to ensure all tests pass |
| 182 | +3. ✅ Run `cargo clippy` to check for common mistakes |
| 183 | +4. ✅ Ensure new code has appropriate test coverage |
| 184 | +5. ✅ Verify no redundant comments are added |
| 185 | + |
| 186 | +## Directory Structure Conventions |
| 187 | + |
| 188 | +- `/src` - Main library source code |
| 189 | +- `/tests` - Integration tests |
| 190 | +- `/examples` - Example usage code |
| 191 | +- `/docs` - Documentation |
| 192 | +- `/benches` - Performance benchmarks |
| 193 | + |
| 194 | +## Common Patterns to Follow |
| 195 | + |
| 196 | +### Logging |
| 197 | +Use the log crate with appropriate macros: |
| 198 | + |
| 199 | +```rust |
| 200 | +use log::{debug, error, info, trace, warn}; |
| 201 | + |
| 202 | +// Examples: |
| 203 | +info!("Starting operation: {}", operation_name); |
| 204 | +debug!("Request details: {:?}", request); |
| 205 | +error!("Operation failed: {}", err); |
| 206 | +``` |
| 207 | + |
| 208 | +### Error Handling |
| 209 | +Use the `Result` type with proper error propagation: |
| 210 | + |
| 211 | +```rust |
| 212 | +use crate::s3::error::Error; |
| 213 | + |
| 214 | +fn operation() -> Result<Response, Error> { |
| 215 | + let result = risky_operation()?; |
| 216 | + Ok(process(result)) |
| 217 | +} |
| 218 | +``` |
| 219 | + |
| 220 | +## Quick Reference |
| 221 | + |
| 222 | +- **Fix formatting**: `cargo fmt --all` |
| 223 | +- **Run tests**: `cargo test` |
| 224 | +- **Run specific test**: `cargo test test_name` |
| 225 | +- **Check code**: `cargo clippy` |
| 226 | +- **Build project**: `cargo build --release` |
| 227 | +- **Generate docs**: `cargo doc --open` |
0 commit comments