@corbat-tech/coding-standards-mcp 1.0.0

package/standards/clean-code/naming.md

@@ -0,0 +1,175 @@
+# Naming Conventions
+
+## Overview
+
+Consistent naming is crucial for code readability. These conventions apply to Java/Kotlin development but principles extend to other languages.
+
+## General Rules
+
+1. **Be descriptive**: Names should reveal intent
+2. **Be consistent**: Same concept = same name throughout codebase
+3. **Be searchable**: Avoid single-letter names except for loops
+4. **Avoid abbreviations**: Use `customerId` not `custId`
+5. **Use domain language**: Names from the ubiquitous language
+
+## Case Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Class | PascalCase | `OrderService` |
+| Interface | PascalCase | `OrderRepository` |
+| Method | camelCase | `calculateTotal()` |
+| Variable | camelCase | `orderTotal` |
+| Constant | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Package | lowercase.separated | `com.company.domain` |
+| Enum | PascalCase | `OrderStatus` |
+| Enum Value | SCREAMING_SNAKE_CASE | `PENDING_PAYMENT` |
+
+## Class Naming
+
+### Entities
+Name after the domain concept:
+```java
+Order, Customer, Product, Invoice
+```
+
+### Value Objects
+Name after what they represent:
+```java
+Money, Email, PhoneNumber, Address, OrderId
+```
+
+### Services
+`[Domain][Action]Service`:
+```java
+OrderPlacementService, PaymentProcessingService
+```
+
+### Repositories
+`[Aggregate]Repository`:
+```java
+OrderRepository, CustomerRepository
+```
+
+### Controllers
+`[Resource]Controller`:
+```java
+OrderController, CustomerController
+```
+
+### Use Cases
+`[Action][Subject]UseCase`:
+```java
+PlaceOrderUseCase, CancelOrderUseCase, GetCustomerUseCase
+```
+
+### DTOs
+`[Purpose][Subject]Dto` or `[Subject][Purpose]`:
+```java
+CreateOrderRequest, OrderResponse, CustomerDto
+```
+
+### Exceptions
+`[Problem]Exception`:
+```java
+OrderNotFoundException, InsufficientFundsException
+```
+
+## Method Naming
+
+### Query Methods (return data, no side effects)
+```java
+findById(), getCustomer(), calculateTotal()
+findAllByStatus(), existsById(), countByType()
+```
+
+### Command Methods (perform actions)
+```java
+save(), delete(), process(), execute()
+placeOrder(), cancelSubscription(), sendNotification()
+```
+
+### Boolean Methods
+Use `is`, `has`, `can`, `should`:
+```java
+isValid(), hasPermission(), canExecute(), shouldRetry()
+isEmpty(), isEnabled(), hasItems()
+```
+
+### Factory Methods
+```java
+of(), from(), create(), valueOf()
+Money.of(100, "USD")
+Order.from(orderDto)
+```
+
+## Variable Naming
+
+### Collections
+Use plural nouns:
+```java
+List<Order> orders;
+Set<Customer> customers;
+Map<OrderId, Order> ordersById;
+```
+
+### Booleans
+Use affirmative names:
+```java
+boolean isActive;    // not: isNotActive
+boolean hasAccess;   // not: noAccess
+boolean enabled;     // not: disabled
+```
+
+### Avoid Noise Words
+```java
+// Bad
+String nameString;
+Customer customerObject;
+List<Order> orderList;
+
+// Good
+String name;
+Customer customer;
+List<Order> orders;
+```
+
+## Test Naming
+
+Use descriptive pattern `should_ExpectedBehavior_When_Condition`:
+
+```java
+@Test
+void should_ThrowException_When_OrderIsEmpty() { }
+
+@Test
+void should_ApplyDiscount_When_CustomerIsPremium() { }
+
+@Test
+void should_ReturnEmptyList_When_NoOrdersExist() { }
+```
+
+Alternative patterns:
+- `givenX_whenY_thenZ`
+- `methodName_StateUnderTest_ExpectedBehavior`
+
+## Package Naming
+
+Follow architecture layers:
+```
+com.company.project.domain.order
+com.company.project.domain.customer
+com.company.project.application.usecase
+com.company.project.infrastructure.persistence
+com.company.project.infrastructure.web
+```
+
+## Anti-Patterns
+
+### Avoid
+- `Manager`, `Handler`, `Processor` (too generic)
+- `Utils`, `Helper`, `Common` (often becomes a dumping ground)
+- `Data`, `Info` (noise words)
+- Hungarian notation (`strName`, `iCount`)
+- Single letters (except `i`, `j`, `k` in loops)
+- Acronyms unless universal (`HTML`, `URL` are OK)

package/standards/clean-code/principles.md

@@ -0,0 +1,179 @@
+# Clean Code Principles
+
+## Overview
+
+Clean code is code that is easy to read, understand, and maintain. These principles, largely from Robert C. Martin, guide the creation of high-quality code.
+
+## Core Principles
+
+### 1. Meaningful Names
+
+Names should reveal intent:
+
+```java
+// Bad
+int d; // elapsed time in days
+
+// Good
+int elapsedTimeInDays;
+```
+
+**Rules:**
+- Use intention-revealing names
+- Avoid disinformation
+- Make meaningful distinctions
+- Use pronounceable names
+- Use searchable names
+- Avoid encodings (Hungarian notation)
+
+### 2. Functions
+
+Functions should be small and do one thing:
+
+```java
+// Bad
+public void processOrder(Order order) {
+    validateOrder(order);
+    calculateTotals(order);
+    applyDiscounts(order);
+    saveOrder(order);
+    sendConfirmationEmail(order);
+    updateInventory(order);
+    notifyWarehouse(order);
+}
+
+// Good
+public void processOrder(Order order) {
+    Order validatedOrder = validateOrder(order);
+    Order pricedOrder = applyPricing(validatedOrder);
+    placeOrder(pricedOrder);
+}
+
+private void placeOrder(Order order) {
+    orderRepository.save(order);
+    eventPublisher.publish(new OrderPlaced(order));
+}
+```
+
+**Rules:**
+- Small (max 20 lines)
+- Do one thing
+- One level of abstraction
+- Max 3-4 parameters
+- No side effects
+- Command-Query Separation
+
+### 3. Comments
+
+Good code is self-documenting. Comments should explain "why", not "what":
+
+```java
+// Bad - explains what (obvious from code)
+// increment counter by one
+counter++;
+
+// Good - explains why
+// We retry 3 times because the external service has transient failures
+private static final int MAX_RETRIES = 3;
+```
+
+**When to comment:**
+- Legal/license headers
+- Explanation of intent
+- Clarification of obscure code
+- Warning of consequences
+- TODO (sparingly)
+- Public API documentation
+
+### 4. Formatting
+
+Consistent formatting improves readability:
+
+- **Vertical**: Related code together, separate concepts with blank lines
+- **Horizontal**: Max 120 characters per line
+- **Indentation**: Consistent (2 or 4 spaces)
+
+### 5. Error Handling
+
+Exceptions over error codes:
+
+```java
+// Bad
+public int withdraw(Money amount) {
+    if (balance.lessThan(amount)) {
+        return -1;  // Error code
+    }
+    balance = balance.subtract(amount);
+    return 0;
+}
+
+// Good
+public void withdraw(Money amount) {
+    if (balance.lessThan(amount)) {
+        throw new InsufficientFundsException(balance, amount);
+    }
+    balance = balance.subtract(amount);
+}
+```
+
+**Rules:**
+- Use exceptions, not error codes
+- Create informative error messages
+- Define exception classes by caller's needs
+- Don't return null
+- Don't pass null
+
+### 6. Classes
+
+Classes should be small and focused:
+
+```java
+// Bad - multiple responsibilities
+public class UserService {
+    public void createUser() { }
+    public void sendEmail() { }
+    public void generateReport() { }
+    public void validatePayment() { }
+}
+
+// Good - single responsibility
+public class UserRegistrationService {
+    public void register(UserRegistrationCommand command) { }
+}
+```
+
+**Rules:**
+- Small (max 200 lines)
+- Single Responsibility Principle
+- High cohesion
+- Low coupling
+
+## SOLID Principles
+
+### S - Single Responsibility
+A class should have only one reason to change.
+
+### O - Open/Closed
+Open for extension, closed for modification.
+
+### L - Liskov Substitution
+Subtypes must be substitutable for their base types.
+
+### I - Interface Segregation
+Many specific interfaces are better than one general interface.
+
+### D - Dependency Inversion
+Depend on abstractions, not concretions.
+
+## Code Smells to Avoid
+
+1. **Long Method**: Methods over 20 lines
+2. **Large Class**: Classes over 200 lines
+3. **Long Parameter List**: More than 4 parameters
+4. **Duplicate Code**: Same code in multiple places
+5. **Dead Code**: Unused code
+6. **Speculative Generality**: Code for "future" needs
+7. **Feature Envy**: Method uses another class's data more than its own
+8. **Data Clumps**: Same data groups appearing together
+9. **Primitive Obsession**: Using primitives instead of small objects
+10. **Switch Statements**: Often indicate missing polymorphism