Хорошо ли видно

Видимость кода: важность читаемости в профессиональной разработке

Да, для меня очень важна хорошая видимость кода. Это один из основных принципов качественной разработки, который влияет на поддерживаемость, отладку и коллаборацию в команде.

Что я понимаю под «видимостью»

Читаемость логики — код должен быть понятен с первого взгляда:

// ❌ ПЛОХО: Не видна логика
public boolean v(User u) {
    return u.age > 18 && u.acc.bal > 0 && u.s == 1;
}

// ✅ ХОРОШО: Видна вся логика
public boolean isEligibleForTransaction(User user) {
    return user.isAdult() 
        && user.account.hasPositiveBalance() 
        && user.status == UserStatus.ACTIVE;
}

Структурная видимость — правильная организация кода по слоям и модулям.

Видимость данных потока выполнения — понятны все шаги обработки запроса.

Техники улучшения видимости

1. Именование

Имена должны быть самодокументирующимися:

// ❌ ПЛОХО
List<Order> o = new ArrayList<>();
for (Order x : orders) {
    if (x.getAmount() > 1000 && x.getStatus() == 2) {
        o.add(x);
    }
}

// ✅ ХОРОШО
List<Order> highValueActiveOrders = new ArrayList<>();
for (Order order : orders) {
    if (order.isHighValue() && order.isActive()) {
        highValueActiveOrders.add(order);
    }
}

// ✅ ЕЩЁ ЛУЧШЕ: Использую stream API
List<Order> highValueActiveOrders = orders.stream()
    .filter(Order::isHighValue)
    .filter(Order::isActive)
    .collect(toList());

2. Длина и сложность методов

Методы должны быть компактными и сосредоточенными:

// ❌ ПЛОХО: Огромный метод, 50+ строк
public Invoice createInvoice(OrderRequest request) {
    // Валидация
    // Расчёты
    // Сохранение
    // Отправка email
    // Логирование
    // Всё в одном методе
}

// ✅ ХОРОШО: Разбит на логические части
public Invoice createInvoice(OrderRequest request) {
    validateRequest(request);
    Invoice invoice = buildInvoice(request);
    invoiceRepository.save(invoice);
    notifyCustomerAsync(invoice);
    return invoice;
}

private void validateRequest(OrderRequest request) { ... }
private Invoice buildInvoice(OrderRequest request) { ... }
private void notifyCustomerAsync(Invoice invoice) { ... }

3. Использование вспомогательных переменных

// ❌ ПЛОХО: Сложное выражение
if (user.getDepartment().getManager().getEmail().contains("@company.com") 
    && user.getStatus() == UserStatus.ACTIVE) {
    // Логика
}

// ✅ ХОРОШО: Разбито на понятные шаги
String managerEmail = user.getDepartment().getManager().getEmail();
boolean isCompanyEmail = managerEmail.contains("@company.com");
boolean isActiveUser = user.getStatus() == UserStatus.ACTIVE;

if (isCompanyEmail && isActiveUser) {
    // Логика
}

4. Логирование и трассировка

Удобно отслеживать что происходит в коде:

@Service
public class PaymentService {
    private static final Logger logger = LoggerFactory.getLogger(PaymentService.class);
    
    public PaymentResult processPayment(Payment payment) {
        logger.info("Starting payment processing: paymentId={}", payment.getId());
        
        try {
            validatePayment(payment);
            logger.debug("Payment validation passed");
            
            PaymentResult result = paymentGateway.charge(payment);
            logger.info("Payment processed successfully: amount={}, status={}", 
                payment.getAmount(), result.getStatus());
            
            return result;
        } catch (PaymentException e) {
            logger.error("Payment processing failed: paymentId={}", payment.getId(), e);
            throw e;
        }
    }
}

5. Правильная структура пакетов

src/main/java/com/company/
├── domain/          # Бизнес логика
│   ├── entity/
│   ├── service/
│   └── repository/
├── application/     # Use cases
│   ├── dto/
│   └── usecase/
├── infrastructure/  # Реализация деталей
│   ├── persistence/
│   └── external/
└── presentation/    # REST контроллеры
    └── controller/

Такая структура делает архитектуру видимой.

Документирование видимости

JavaDoc для публичных API:

/**
 * Создаёт новый заказ на основе запроса.
 * 
 * @param request запрос на создание заказа, не может быть null
 * @return созданный заказ с ID
 * @throws InvalidOrderException если заказ не прошёл валидацию
 * @throws PaymentException если не удалось обработать платёж
 */
public Order createOrder(@NonNull OrderRequest request) 
    throws InvalidOrderException, PaymentException {
    // Реализация
}

Комментарии для сложной логики:

public class InventoryService {
    
    public boolean reserveStock(Long productId, int quantity) {
        // Используем SELECT FOR UPDATE для избежания race condition:
        // несколько потоков могут одновременно зарезервировать один товар.
        // Эта блокировка гарантирует атомарность операции.
        
        Stock stock = stockRepository.findByIdForUpdate(productId);
        if (stock.getAvailableQuantity() >= quantity) {
            stock.decreaseQuantity(quantity);
            stockRepository.save(stock);
            return true;
        }
        return false;
    }
}

Инструменты для улучшения видимости

IDE Features:

• Code folding для скрытия нерелевантных деталей
• Структурная навигация (Structure view)
• Jump to definition
• Highlighting похожих переменных

Static Analysis:

# Проверка качества кода
mvn clean verify  # Запускает все проверки
mvn sonar:sonar   # SonarQube анализ

Тестирование документирует видимость:

@Test
public void shouldCalculateOrderTotalCorrectly() {
    // Given (предусловие)
    Order order = new Order();
    order.addItem(new OrderItem(100, 2));  // 2 товара по 100
    
    // When (действие)
    BigDecimal total = order.calculateTotal();
    
    // Then (ожидаемый результат)
    assertEquals(BigDecimal.valueOf(200), total);
}

Тест — это документация того, как именно работает код.

Практический пример из опыта

Работал с legacy кодом без видимости:

// До: Невозможно понять что происходит
public class OldUserService {
    public void process(User u, int t) {
        if (u.a > 18 && t == 1) {
            // 500 строк непонятной логики
        }
    }
}

// После: Кристально ясно
public class UserService {
    public void sendWelcomeEmailToAdults(User user, EmailType emailType) {
        if (user.isAdult() && emailType.isWelcomeType()) {
            emailService.sendWelcomeEmail(user);
        }
    }
}

Второй вариант сразу понятен, легче поддерживается и проще тестируется.

Заключение

Хорошая видимость кода — это инвестиция в:

• Скорость разработки — меньше времени на понимание
• Качество — меньше багов, потому что логика ясна
• Командную работу — другие разработчики легче врубаются
• Поддержку — через год легче вспомнить, почему так написано

Это именно то, что отличает профессиональный код от пролучайного набора строк.