2G

Developer guidelines usually start life as team checklists, but those checklists only help when people can understand the reasoning behind them. This post turns a broad set of engineering standards into a practical field guide: how to pick ready work, write code that stays maintainable, operate services safely, and ship changes with fewer avoidable mistakes.

The goal is not to create a process for its own sake. The goal is to reduce the classes of problems that repeatedly slow teams down: unclear story scope, oversized classes, poor logging, unsafe schema changes, brittle APIs, weak CI gates, and preventable security issues.

How to Use This Guide

• Use it when starting a new story to check readiness and definition of done.
• Use it during implementation to keep code, database, and API decisions aligned with team standards.
• Use it in code review to spot issues before they become production problems.
• Use it as onboarding material for engineers who need the team’s default expectations in one place.

General

These are the habits that shape delivery quality before code is even merged.

Why this matters: Teams lose time when work starts before the story is clear or when “done” means different things to different people. A small amount of discipline here prevents churn later.

Object-Oriented Design

This section focuses on maintainability. Most long-term codebase pain comes from weak boundaries, unclear names, and methods that do too much.

OOP Checklist

Code Example: Tell-Don’t-Ask

// ❌ BAD — asks for state, then acts on it outside the object
if (order.getStatus().equals("PENDING") && order.getTotal() > 0) {
    order.setStatus("PROCESSING");
    paymentService.charge(order.getTotal());
}
// ✅ GOOD — tells the order to process itself
order.process(paymentService);
// Order encapsulates the status check and state transition

Code Example: Extract Small Methods

// ❌ BAD — 40-line method doing 4 things
public void handleOrder(Order order) {
    // 10 lines of validation
    // 10 lines of pricing calculation
    // 10 lines of inventory check
    // 10 lines of payment processing
}
// ✅ GOOD — each concern is named and testable
public void handleOrder(Order order) {
    validateOrder(order);
    Price price = calculatePrice(order);
    reserveInventory(order);
    processPayment(order, price);
}

Key takeaway: Keep behaviour close to the object that owns it, keep units of code small, and optimise for code that is easy to read and safe to change.

Logging

Logs are not just debugging output. They are operational evidence when something goes wrong in production.

Log Level Guide

// DEBUG — developer detail, disabled in production
log.debug("Entering calculateDiscount with orderId={}", orderId);
// INFO — normal business events
log.info("Order processed successfully. orderId={}, amount={}", orderId, amount);
// WARN — unexpected state, service still working
log.warn("Payment retry attempt {} for orderId={}", retryCount, orderId);
// ERROR — exception caught, operation failed
log.error("Failed to process payment for orderId={}. Cause: {}", orderId, e.getMessage(), e);

Danger: ANTI-PATTERN

// ❌ Never log PII
log.info("User {} with email {} placed order", user.getName(), user.getEmail());
// ✅ Log IDs only
log.info("User {} placed order {}", user.getId(), orderId);

Key takeaway: good logs help you reconstruct what happened across services without exposing sensitive data.

Database

Database changes deserve extra caution because application versions often overlap during deployment. A schema that works only for the newest code is not safe enough.

Index Creation Rule

Create an index when a column appears in WHERE, JOIN ON, or ORDER BY on a table with > 10k rows. Verify with EXPLAIN ANALYSE:

EXPLAIN ANALYSE SELECT * FROM orders WHERE user_id = 123;
-- Look for "Seq Scan" on large tables — that's a missing index
-- "Index Scan" means the index is being used

Common Mistakes to Avoid

• Adding schema changes manually in production instead of through versioned migrations
• Creating indexes without confirming an actual query pattern or execution plan needs
• Ignoring table growth until cleanup, partitioning, or archival becomes urgent

Key takeaway: Treat schema design as an operational concern, not just a modelling exercise.

REST / Events

Interfaces outlive implementations. API and event conventions need to be predictable because other systems build against them.

REST Naming Conventions

# ✅ Good
GET    /orders                → list orders
GET    /orders/{id}           → get one order
POST   /orders                → create order
PUT    /orders/{id}           → replace order
PATCH  /orders/{id}           → partial update
DELETE /orders/{id}           → delete order
# ❌ Bad
GET    /getOrders
POST   /createOrder
GET    /orders/getById/{id}

Key takeaway: Stable, conventional interfaces reduce client confusion and make integrations easier to test and maintain.

HTTP Client

Outbound calls are one of the fastest ways for a healthy service to become unhealthy. Defaults are often unsafe.

Timeout Configuration Example (Spring RestTemplate / WebClient)

// ✅ Configure all timeouts — never use defaults
HttpClient httpClient = HttpClient.create()
    .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)     // 5s connect
    .responseTimeout(Duration.ofSeconds(10))                 // 10s read
    .doOnConnected(conn ->
        conn.addHandlerLast(new ReadTimeoutHandler(10))
            .addHandlerLast(new WriteTimeoutHandler(10)));

Danger: ANTI-PATTERN

Using default HTTP client timeouts (often infinite).

An external service that hangs will hold your thread indefinitely. Under load, this exhausts your thread pool and cascades into a full outage. Always set explicit timeouts.

Key takeaway: Every external dependency needs timeout, pooling, and failure-isolation settings before it is production-ready.

CI Pipeline

The CI pipeline is the automated version of team discipline. If quality checks are optional, they eventually become inconsistent.

Key takeaway: CI should block low-quality or risky changes early, before they become review fatigue or production incidents.

Code Repository Structure

Repository structure affects how quickly engineers can understand, navigate, and safely change a service.

Key takeaway: Organise repositories around business capability and discoverability, not convenience for the first developer who created them.

Security

Security guidelines are engineering defaults, not a separate phase at the end of delivery.

Key takeaway: Most avoidable security issues come from weak defaults, not advanced attacks. Build the safe path into normal development.

Developer Tools and Plugins

Tooling should remove friction, not add ceremony. The right defaults improve code quality before review starts.

IntelliJ IDEA recommended plugins:

Terminal: iTerm2 + Zsh + Oh My Zsh

Mocking Services

When dependencies are unavailable, expensive, or hard to control, service virtualisation keeps development and testing moving.

Clean Code References

• Code Smells Part I – DZone

Final Takeaways

• Start only with stories that are clear, testable, and aligned with what “done” means.
• Keep code small, intention-revealing, and easy to change.
• Treat logging, database changes, and external calls as operational design concerns.
• Make interfaces predictable and CI enforcement non-optional.
• Build security and maintainability into the default workflow instead of relying on heroics later.
• Refactoring Catalogue – Fowler
• Clean Code Summary Cheatsheet

Written by

Balaji G