DEV Community: Minuth Prom

Clean Code and Software Design Principles

Minuth Prom — Wed, 21 Jan 2026 18:14:45 +0000

Essential practices for writing maintainable, scalable, and collaborative software.

1. Meaningful Names

Use descriptive, unambiguous names for variables, functions, classes, and modules.
Use consistent formatting (e.g., camelCase, PascalCase, snake_case).

Example:

// Bad
const d = new Date();
const usr = getUsr();
function calc(a: number, b: number): number { return a * b * 0.15; }

// Good
const currentDate = new Date();
const activeUser = getActiveUser();
function calculateTaxAmount(price: number, quantity: number): number {
  const TAX_RATE = 0.15;
  return price * quantity * TAX_RATE;
}

2. Functions

Focus on a single task.
Use names that describe the function's purpose.
Avoid excessive nested functions.
Use object parameters if the function has many parameters.

Example:

// Bad
class UserService {
  registerUser(user: User) {
    this.validate(user);
  }

  private validate(user: User) {
    if (!user.email) {
      throw new Error("Email required");
    }
    this.save(user);
  }

  private save(user: User) {
    // pretend DB save
    console.log("Saving user:", user.name);
    this.sendWelcome(user);
  }

  private sendWelcome(user: User) {
    console.log("Sending welcome email to:", user.email);
  }
}
// Good
class UserService {
  registerUser(user: User) {
    this.validate(user);
    this.save(user);
    this.sendWelcome(user);
  }

  private validate(user: User) {
    if (!user.email) {
      throw new Error("Email required");
    }
  }

  private save(user: User) {
    // pretend DB save
    console.log("Saving user:", user.name);
  }

  private sendWelcome(user: User) {
    console.log("Sending welcome email to:", user.email);
  }
}

3. Comments

Use comments to explain unclear code.

4. Flat is better than nested

Avoid nested structures that make your code difficult to read. Example:

// Bad - Nested conditions
function validateUser(user: User) {
  if (user) {
    if (user.email) {
      if (user.age >= 18) {
        return true;
      } else {
        return false;
      }
    } else {
      return false;
    }
  } else {
    return false;
  }
}
// Good - Early returns to reduce nesting
function validateUser(user: User) {
  if (!user) return false;
  if (!user.email) return false;
  if (user.age < 18) return false;
  return true;
}

5. SOLID Principles

Single Responsibility Principle (SRP): A class or function should have only one responsibility. Example:

// Bad - Single class with multiple responsibilities
class UserManager {
  // User-related responsibility
  createUser(name: string, email: string) {
    console.log(`User created: ${name}, ${email}`);
  }

  // Unrelated responsibility: file operations
  writeFile(content: string) {
    console.log(`Writing file with content: ${content}`);
  }

  // Unrelated responsibility: math utility
  calculateTax(amount: number) {
    return amount * 0.1;
  }
}

// Good - Separate classes for each responsibility
class UserService {
  createUser(name: string, email: string) {
    console.log(`User created: ${name}, ${email}`);
  }
}
class FileService {
  writeFile(content: string) {
    console.log(`Writing file with content: ${content}`);
  }
}
class TaxCalculator {
  calculateTax(amount: number) {
    return amount * 0.1;
  }
}

Open/Closed Principle (OCP): Open for extension, closed for modification. Example:

// Bad - Modifying existing code to add new shapes
class AreaCalculator {
    calculateArea(shape: any): number {
        if (shape.type === "circle") {
            return Math.PI * shape.radius * shape.radius;
        } else if (shape.type === "rectangle") {
            return shape.width * shape.height;
        }
        // Adding new shapes requires modifying this method
    }
}

// Good - Extending functionality without modifying existing code
interface Shape {
    area(): number;
}
class Circle implements Shape {
    constructor(private radius: number) {}
    area(): number {
        return Math.PI * this.radius * this.radius;
    }
}
class Rectangle implements Shape {
    constructor(private width: number, private height: number) {}
    area(): number {
        return this.width * this.height;
    }
}
class AreaCalculator {
    calculateArea(shape: Shape): number {
        return shape.area();
    }
}

Liskov Substitution Principle (LSP): Derived classes must be substitutable for base classes. Example:

// Bad - Subclass that violates LSP
class Bird {
    fly(): void {
        console.log("Flying");
    }
}
class Ostrich extends Bird {
    fly(): void {
        throw new Error("Ostriches can't fly!");
    }
}
// Good - Separate hierarchy for non-flying birds
class Bird {
    eat(): void {
        console.log("Eating");
    }
}

class FlyingBird extends Bird {
    fly(): void {
        console.log("Flying");
    }
}
class Ostrich extends Bird {
    // Ostrich does not have fly method
}

Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they don't use. Example:

// Bad - Fat interface
interface Worker {
    work(): void;
    eat(): void;
}
class HumanWorker implements Worker {
    work(): void {
        console.log("Working");
    }
    eat(): void {
        console.log("Eating");
    }
}
class RobotWorker implements Worker {   
    work(): void {
        console.log("Working");
    }
    // Robot does not eat, but forced to implement eat()
    eat(): void {
        throw new Error("Robots don't eat!");
    }
}

// Good - Segregated interfaces
interface Workable {
    work(): void;
}
interface Eatable {
    eat(): void;
}
class HumanWorker implements Workable, Eatable {
    work(): void {
        console.log("Working");
    }
    eat(): void {
        console.log("Eating");
    }
}
class RobotWorker implements Workable {   
    work(): void {
        console.log("Working");
    }
}

Dependency Inversion Principle (DIP): Depend on abstractions, not concretions. Example:

// Bad - High-level module depends on low-level module
class MySQLDatabase {
    connect(): void {
        console.log("Connected to MySQL");
    }
}
class UserService {
    private database: MySQLDatabase;
    constructor() {
        this.database = new MySQLDatabase();
    }
    getUser(): void {
        this.database.connect();
        console.log("Fetching user");
    }
}

// Good - Both high-level and low-level modules depend on abstractions
interface Database {
    connect(): void;
}
class MySQLDatabase implements Database {
    connect(): void {
        console.log("Connected to MySQL");
    }
}
class PostgreSQLDatabase implements Database {
    connect(): void {
        console.log("Connected to PostgreSQL");
    }
}
class UserService {
    private database: Database;
    constructor(database: Database) {
        this.database = database;
    }
    getUser(): void {
        this.database.connect();
        console.log("Fetching user");
    }
}
// Usage
new UserService(new MySQLDatabase())
new UserService(new PostgreSQLDatabase())

6. Clean Architecture

Layer Separation: Separate layers by role (e.g., Service, Repository, Controller).
Dependency Rule: Follow the Dependency Inversion Principle to ensure high-level modules don't depend on low-level modules.
Independence: Business logic should not depend on frameworks, UI, or databases.
Testability: Easy to test without external dependencies.

Example (Layered Architecture):

// Domain Layer
class User {
    constructor(public id: number, public name: string) {}
}
interface UserRepository {
    getUserById(id: number): User;
}

class InMemoryUserRepository implements UserRepository {
    private users: User[] = [new User(1, "Alice"), new User(2, "Bob")];
    getUserById(id: number): User {
        return this.users.find(user => user.id === id);
    }
}

// Application Layer
class UserService {
    constructor(private userRepository: UserRepository) {}
    getUserProfile(id: number): User {
        return this.userRepository.getUserById(id);
    }
}

class UserController {
    constructor(private userService: UserService) {}
    getUserProfile(id: number): void {
        const user = this.userService.getUserProfile(id);
        console.log(`User Profile: ${user.name}`);
    }
}
// Usage
const userRepository = new InMemoryUserRepository();
const userService = new UserService(userRepository);
const userController = new UserController(userService);
userController.getUserProfile(1);

Are You Using Interfaces the Right Way?

Minuth Prom — Sat, 18 Oct 2025 09:34:20 +0000

Let’s be honest. Many developers use interfaces without fully understanding their purpose. Ask yourself:

Are you using interfaces just to list method names?
As a replacement for public static final constants?
Because a design pattern told you to?
Or simply because you’ve seen others do it?

If yes, it’s time to rethink what interfaces are truly for — and how they can make your code more flexible, testable, and scalable.

What Is an Interface Really For?

In object-oriented programming (OOP), an interface defines a contract — a set of behaviors that a class must implement. It’s not about organizing methods. It’s about enabling polymorphism: different objects of the same type perform the same action but produce different results.

Let’s focus on how interfaces are used in Java, especially in service layers and common design patterns.

Why Do We Create Interfaces Before Implementing Classes?

You’ve likely seen this pattern:

Define an interface first
Then create a class that implements it

But why bother? After all, we could just write the class directly and everything would still work — no errors, no complaints.

If you think interfaces are just for listing method names, you’re missing their true purpose.

The Real Reason: Flexibility Through Dependency Injection

Interfaces are essential for enabling Dependency Injection (DI) and following the Dependency Inversion Principle — the “I” in SOLID.

Let’s take a real-world example:

POS Machine Example

Imagine a POS machine that can process Visa, MasterCard, and UnionPay. Each card is a dependency. The POS machine should not care which card it’s using — it should rely on a shared interface like Card.

If a new card type is introduced, you simply implement the Card interface. The POS machine doesn’t need to change at all.

Without DI and interfaces, each card would require its own custom POS machine — rigid, expensive, and hard to maintain.

Interfaces as Specifications in Libraries and Frameworks

Interfaces also serve as specification contracts in frameworks and libraries.

Take Spring Security, for example. It allows you to customize user retrieval logic by implementing the UserDetailsService interface. You don’t need to modify the framework — just plug in your own logic.

This is how frameworks stay flexible and extensible.

Interfaces aren’t just for listing methods. They’re contracts that make your code flexible, testable, and scalable.

Best Practices for Using Interfaces

Not every method belongs in an interface — internal or private logic should stay out.
Keep interfaces focused — don’t lump everything into one giant interface.
Avoid using interfaces just to “see method names” — that’s not their purpose.
Don’t use interfaces as a replacement for public static final constants — use enums or final classes instead.
Design interfaces to support testing and future changes.

Centralize Your API Documents with Docura

Minuth Prom — Sun, 24 Aug 2025 04:47:43 +0000

Just wanted to share a little side project I’ve been working on: Docura. It’s basically a super simple platform that lets you chuck all your OpenAPI specs in one place and view them without any setup headaches.

No more digging through folders or random URLs to find your API docs. Just point Docura at your specs and boom—all your endpoints, neatly in one spot with a clean UI.

Focused just on viewing OpenAPI right now
Super easy to set up — just run npx create-docura-app docura-demo and you’re done
Great if you have multiple APIs or want your team to stop bugging you for docs 😉

Want to see it in action?

👉 Live demo here!

Check it out if you’re into that kind of thing: minuth/docura on GitHub

Would love feedback or ideas!.

Simplify Web Frontend Environment Variable Management with Browset

Minuth Prom — Sun, 14 Jul 2024 16:43:50 +0000

GitHub repository

I'm excited to introduce Browset, an open-source web platform designed to simplify the management of environment variables for web frontends. Inspired by the complexities of managing different stages like UAT and Production, Browset provides a dynamic solution that eliminates the need for rebuilds.

Why We Need Browset?

Managing environment variables for web frontends can be cumbersome and complex, especially when deploying across multiple stages. Traditional methods often require intricate setups and rebuilds for each environment, as outlined in this article. Browset addresses this issue by providing a streamlined and efficient solution, eliminating the need for such complex implementations.

How Browset Solves the Problem?

Browset allows you to create a project, providing a unique random key to access the GET request API endpoint (/api/v1/environments/variables/{project-key}) to retrieve environment variables. You can then create environment variables for each stage within that project. For instance, if your web frontend has two stages (UAT and Production), you can define the environment variables for each stage as follows:

UAT

Domain: https://uat.mywebsite.com
Environment Variables: API_URL=https://api.uat.mywebsite.com

Production

Domain: https://mywebsite.com
Environment Variables: API_URL=https://api.mywebsite.com

Once the environment variables are created for each stage of the project, you can integrate Browset with your web frontend to load the environment variables dynamically.

Example Integration

Assume your Browset platform is hosted at https://browset-server.com. In your web frontend, make a GET request to https://browset-server.com/api/v1/environments/variables/{project-key}. The response will provide the environment variables in JSON format as key-value pairs.

For example:

Request from UAT: If you make a request from https://uat.mywebsite.com, you will receive:

  {
    "API_URL": "https://api.uat.mywebsite.com"
  }

Request from Production: If you make a request from https://mywebsite.com, you will receive:

  {
    "API_URL": "https://api.mywebsite.com"
  }

This dynamic response based on the origin domain ensures that you don't need to rebuild your web frontend each time you deploy to a different stage or update a variable. With Browset, you build once and run anywhere.

Benefits of Using Browset

Simplifies Environment Management: Manage environment variables effortlessly across different stages.
No Rebuilds Required: Deploy updates without the need for rebuilding the frontend.
Dynamic Configuration: Environment variables are dynamically served based on the origin domain.
Streamlined Process: Reduces the complexity involved in traditional methods of managing environment-specific configurations.

Dockerized Spring Boot with Multi-Environment Configs

Minuth Prom — Wed, 03 Jul 2024 16:04:43 +0000

Dockerizing a Spring Boot application for multiple environments involves creating Docker images that can be configured differently based on the deployment environment (development, testing, production, etc.). This ensures that the application behaves consistently across various development and deployment stages.

We will use Docker Multi-Stage and Spring Boot Externalized Configuration in this configuration.

Using Docker Multi-Stage builds allows for creating smaller, more efficient Docker images by separating the build process into multiple stages. This reduces the final image size. More detail about Multi-stage builds | Docker Docs.

Spring Boot Externalized Configuration, on the other hand, enables the application to be easily reconfigured for different environments without changing the code. This is achieved by externalizing environment-specific configurations, making the application more flexible and easier to manage across development, testing, and production environments. More detail about Externalized Configuration :: Spring Boot

Gradle Project

Dockerfile

# Stage 1: Build the application
FROM gradle:8.8-jdk17 AS build

# Set the working directory in the container
WORKDIR /app

# Copy the Gradle build files
COPY build.gradle settings.gradle ./

# Copy the source code
COPY src ./src

# Build the application
RUN gradle build --no-daemon

# Stage 2: Create the runtime image
FROM openjdk:17-jdk-slim

# Set the working directory in the container
WORKDIR /app

# Copy the built JAR file from the Gradle build stage
COPY --from=build /app/build/libs/*.jar app.jar

# Expose the port the application runs on
EXPOSE 8080

# Command to run the application
ENTRYPOINT ["java", "-jar", "app.jar", "--spring.config.location=optional:classpath:/,optional:file:config/"]

.dockerignore

# Ignore build directory where Gradle output files are stored
build/

# Ignore Gradle wrapper files
gradle/wrapper/gradle-wrapper.jar
gradle/wrapper/gradle-wrapper.properties

# Ignore IntelliJ IDEA project files
*.iml
.idea/

# Ignore Eclipse project files
.project
.classpath
.settings/

# Ignore NetBeans project files
nbproject/

# Ignore Mac OS X folder attributes
.DS_Store

# Ignore Linux trash files
.Trash-*

# Ignore node_modules if there's any front-end part
node_modules/

# Ignore log files
*.log

# Ignore temporary files
*.tmp
*.swp
*.swo

# Ignore backup and old files
*.bak
*.old

# Ignore environment files (optional, if you use them)
.env
.env.local

Maven Project

Dockerfile

# Stage 1: Build the application
FROM maven:3.8.4-openjdk-17 AS build

# Set the working directory in the container
WORKDIR /app

# Copy the pom.xml and download dependencies
COPY pom.xml ./
RUN mvn dependency:go-offline -B

# Copy the source code and build the application
COPY src ./src
RUN mvn package -DskipTests

# Stage 2: Create the runtime image
FROM openjdk:17-jdk-slim

# Set the working directory in the container
WORKDIR /app

# Copy the jar file from the build stage
COPY --from=build /app/target/*.jar app.jar

# Expose the port the application runs on
EXPOSE 8080

# Command to run the application
ENTRYPOINT ["java", "-jar", "app.jar", "--spring.config.location=optional:classpath:/,optional:file:config/"]

.dockerignore

# Ignore target directory where Maven output files are stored
target/

# Ignore Maven local repository (optional)
.m2/

# Ignore IntelliJ IDEA project files
*.iml
.idea/

# Ignore Eclipse project files
.project
.classpath
.settings/

# Ignore NetBeans project files
nbproject/

# Ignore Mac OS X folder attributes
.DS_Store

# Ignore Linux trash files
.Trash-*

# Ignore node_modules if there's any front-end part
node_modules/

# Ignore log files
*.log

# Ignore temporary files
*.tmp
*.swp
*.swo

# Ignore build output
build/

# Ignore other files that are not needed in the image
*.bak
*.old

# Ignore environment files (optional, if you use them)
.env
.env.local

The --spring.config.location=optional:classpath:/,optional:file:config/ parameter is used to specify the locations from which Spring Boot should load its configuration files. Here's a breakdown of what it does:

optional:classpath:/: This tells Spring Boot to look for configuration files on the classpath (typically inside the JAR file). The optional: prefix means that Spring Boot will not fail if the configuration file is not found in this location.
optional:file:config/: This tells Spring Boot to look for configuration files in the config/ directory on the file system in the container.

By using this parameter, you can externalize your configuration files, making it easier to manage different configurations for different environments (development, testing, production) without changing the application code. This is particularly useful when you want to override default configurations with environment-specific settings.

In the context of the provided Dockerfile, this parameter allows the Docker container to use configuration files from the config/ directory, which is mapped to a volume on the host machine. This way, you can easily update configuration settings without rebuilding the Docker image.

Build and run without Docker Compose file

Build: docker build -t springboot-dockerize .
Run: docker run -p 8081:8080 -v D:/configuration/demo-spring-boot-dockerize/:/app/config/ springboot-dockerize
- -p 8081:8080: This flag maps port 8081 on the host machine to port 8080 on the container. It allows you to access the application running inside the container via port 8081 on the host.
- -v D:/configuration/demo-spring-boot-dockerize/:/app/config/: This flag mounts the directory D:/configuration/demo-spring-boot-dockerize/ from the host machine to the /app/config/ directory inside the container. This is used to provide external configuration.

Using Docker Compose file

version: '3.8'

services:
  springboot-app:
    image: springboot-dockerize
    ports:
      - "${HOST_PORT}:8080"
    volumes:
      - "${CONFIG_PATH}:/app/config/"

Using environment variables HOST_PORT and CONFIG_PATH allows for flexibility and reusability of the Docker Compose configuration.

Run with system environment variables or .env file: docker compose up --build

Make sure to set the environment variables HOST_PORT and CONFIG_PATH in your system or in a .env file in the same directory as your docker-compose.yml:
```
HOST_PORT=8081
CONFIG_PATH=D:/configuration/demo-spring-boot-dockerize/
```
Run with inline environment variable: HOST_PORT=8081 CONFIG_PATH=D:/configuration/demo-spring-boot-dockerize/ docker compose up --build

Visualize your GitHub repository statistics using GitHub Actions

Minuth Prom — Sun, 14 May 2023 07:56:29 +0000

What I built

I built a custom GitHub Actions named Quick Chart Report that able to generate chart images that display repository statistics such as issues, pull requests, and more.

Category Submission:

Maintainer Must-Haves

App Link

Repository
Marketpalce

Screenshots

Description

The Quick Chart Report is an essential tool for GitHub users who want to easily visualize their repository statistics. The Quick Chart Report action automatically generate chart images that display repository statistics such as issues, pull requests, and more, when triggered by events such as opening or closing an issue or pull request, or other GitHub events, or by a schedule.

Link to Source Code

https://github.com/minuth/quickchart-report

Permissive License

MIT

Background (What made you decide to build this particular app? What inspired you?)

My motivation for creating this project was to provide a convenient way for the maintainer to visualize the key statistics of the repository, such as the number of issues, pull requests and other metrics, in a single image that displays a chart.

How I built it (How did you utilize GitHub Actions or GitHub Codespaces? Did you learn something new along the way? Pick up a new skill?)

This project is a result of combining Composite Typescript GitHub Actions with my own utility GitHub Action called Repository Report. The Repository Report action retrieves various statistics about a GitHub repository and outputs them as a JSON string. To visualize the JSON data as a chart image, I used QuickChart, a tool that creates chart images from data. This project helped me learn about Composite GitHub Actions, which I was not familiar with before.

Additional Resources/Info

Repository report
- Repository
- Marketplace
QuickChart
QuickChart limitations
Example project that used Quick Chart Report to generate the chart image and display it in README file.