# Code Style and Conventions Standards for Clean Code

This document outlines the code style and conventions standards for projects adhering to Clean Code principles. These standards aim to enhance readability, maintainability, and collaboration within development teams. They focus specifically on the stylistic aspects of code that contribute to its overall cleanliness, clarity, and consistency.

## 1. General Formatting Principles

### 1.1. Code Layout

**Do This:**

* Use consistent indentation (typically 2 or 4 spaces, but be consistent within the project). Decide on one and stick to it.

* Maintain a maximum line length of 120 characters (or whatever is agreed upon by the dev team) to improve readability.

* Use blank lines judiciously to separate logical sections of code, such as between methods or classes and within functions to delineate distinct steps.

**Don't Do This:**

* Use tabs for indentation (mix of tabs and spaces leads to inconsistencies).

* Write extremely long lines that require horizontal scrolling.

* Omit blank lines, leading to dense, unreadable code.

**Why:** Consistent formatting reduces cognitive load, allowing developers to focus on the code's logic rather than its presentation. Readability directly impacts how quickly and accurately code can be understood and maintained.

**Example:**

"""python

# Good formatting with indentation and blank lines

def calculate_area(width, height):

if width <= 0 or height <= 0:

raise ValueError("Width and height must be positive values.")

area = width * height

return area

# Bad formatting - Dense and hard to read

def calculate_area(width, height):

if width<=0 or height<=0:raise ValueError("Width and height must be positive values.")

area=width*height

return area

"""

### 1.2. Vertical Spacing

**Do This:**

* Separate classes, methods, and logical blocks of code with blank lines.

* Group related statements together.

* Maintain a consistent vertical density.

**Don't Do This:**

* Place multiple statements on a single line.

* Leave excessive blank lines, creating sparse code.

* Mix tightly coupled statements with distant separation.

**Why:** Clear vertical separation helps readers visually parse the code's structure, revealing relationships between code blocks and enhancing comprehension.

**Example:**

"""java

// Good vertical spacing

public class Rectangle {

private int width;

private int height;

public Rectangle(int width, int height) {

this.width = width;

this.height = height;

}

public int calculateArea() {

return width * height;

}

// Poor vertical spacing (hard to read)

public class Rectangle {private int width; private int height;

public Rectangle(int width, int height) {this.width = width; this.height = height;}

public int calculateArea() {return width * height;}}

"""

### 1.3. Horizontal Spacing

**Do This:**

* Use spaces around operators (=, +, -, *, /, etc.) to improve readability.

* Use spaces after commas in argument lists.

* Align equal signs in variable declarations (use with caution, only when it enhances readability substantially).

**Don't Do This:**

* Omit spaces around operators, making expressions difficult to parse.

* Crowd arguments together without spaces.

* Overuse alignment, leading to brittle code.

**Why:** Consistent horizontal spacing makes code visually appealing and easier to read, reducing the chance of misinterpreting complex expressions.

**Example:**

"""javascript

// Good horizontal spacing

let x = 10 + 5;

const message = "Hello, world!";

function myFunction(arg1, arg2) { ... }

// Bad horizontal spacing

let x=10+5;

const message="Hello, world!";

function myFunction(arg1,arg2) {...}

"""

### 1.4. Indentation

**Do This:**

* Use consistent indentation (2 or 4 spaces) for each level of nesting.

* Indent code blocks within control structures (if, else, for, while, switch).

* Ensure that indentation is correct after multi-line statements.

**Don't Do This:**

* Mix tabs and spaces for indentation.

* Use inconsistent indentation levels.

* Fail to indent code blocks, making control flow ambiguous.

**Why:** Proper indentation visually represents the code's structure, making it easy to follow the control flow and understand the relationship between different code blocks. Inconsistent indentention leads to errors and is hard to debug.

**Example:**

"""csharp

// Good Indentation

public void ProcessData(bool isValid) {

if (isValid) {

Console.WriteLine("Data is valid.");

// Perform some operations

ProcessValidData();

} else {

Console.WriteLine("Data is invalid.");

// Handle invalid data

HandleInvalidData();

}

// Bad Indentation

public void ProcessData(bool isValid) {

if (isValid) {

Console.WriteLine("Data is valid.");

// Perform some operations

ProcessValidData();

} else {

Console.WriteLine("Data is invalid.");

// Handle invalid data

HandleInvalidData();

}

"""

## 2. Naming Conventions

### 2.1. General Naming

**Do This:**

* Use descriptive and meaningful names that clearly indicate the purpose of variables, methods, and classes.

* Choose names that are pronounceable and easy to remember.

* Use consistent terminology throughout the codebase.

**Don't Do This:**

* Use single-letter variable names (except for loop counters).

* Use cryptic abbreviations that are difficult to understand.

* Use inconsistent naming conventions.

**Why:** Naming is crucial for code readability. Descriptive names make code self-documenting, reducing the need for comments and making it easier to understand the code's intent.

**Example:**

"""python

# Good naming

class UserAccount: # Class represents a user account

def __init__(self, username, password):

self.username = username # username for the user account

self.password = password # password for the user account

def is_valid_password(self, password_attempt):

return self.password == password_attempt # checks if the password attempt is the valid password

# Bad naming

class UA: # What does UA represent

def __init__(self, u, p):

self.u = u # what is u

self.p = p # what is p

def vpw(self, pw_a):

return self.p == pw_a # what does vpw, p, and pw_a mean?

"""

### 2.2. Class Naming

**Do This:**

* Use nouns or noun phrases for class names (e.g., "Customer", "OrderService").

* Capitalize the first letter of each word (PascalCase/UpperCamelCase).

**Don't Do This:**

* Use verbs or verb phrases for class names.

* Use lowercase or snake_case for class names.

**Why:** Class names represent objects or concepts, so nouns are appropriate. Consistent capitalization improves readability and distinguishes classes from variables and methods.

**Example:**

"""java

// Good class naming

public class OrderProcessor { ... }

public class CustomerAccount { ... }

// Bad class naming

public class processOrder { ... } // should be OrderProcessor

public class customer_account { ... } // should be CustomerAccount

"""

### 2.3. Method Naming 🚀

**Do This:**

* Use verbs or verb phrases for method names (e.g., "calculateTotal", "validateInput").

* Use camelCase (first word lowercase, subsequent words capitalized).

* Follow the principle of least astonishment: methods should do what their name suggests.

**Don't Do This:**

* Use nouns or noun phrases for method names.

* Use PascalCase/UpperCamelCase for method names.

* Create methods with unexpected side effects.

**Why:** Method names represent actions or operations, so verbs are appropriate. CamelCase distinguishes methods from classes and variables. Least Astonishment improves usability and reduces bugs.

**Example:**

"""csharp

// Good method naming

public int CalculateTotalAmount() { ... }

public bool IsValidInput(string input) { ... }

// Bad method naming

public int TotalAmount() { ... } // should be CalculateTotalAmount

public bool valid_input(string input) { ... } // should be IsValidInput following camelCase

"""

### 2.4. Variable Naming

**Do This:**

* Use descriptive names that reflect the variable's purpose.

* Use camelCase for instance and local variables.

* Use all uppercase with underscores for constants (e.g., "MAX_VALUE").

* Be mindful of scope, longer names are acceptable for larger scopes

**Don't Do This:**

* Use single-letter variable names (except for loop counters).

* Use abbreviations that are not widely understood.

* Use names that conflict with reserved keywords.

**Why:** Clear variable names make it easier to understand the code's logic. Consistent casing improves readability and distinguishes variables from other code elements.

**Example:**

"""javascript

// Good variable naming

let customerName = "John Doe";

const MAX_ATTEMPTS = 3;

let itemCount = 0;

// Bad variable naming

let cn = "John Doe"; // ambiguous abbreviation

const ma = 3; // ambiguous abbreviation

let i = 0; // not descriptive

"""

### 2.5. Boolean Variables and Methods

**Do This:**

* Name boolean variables and methods to clearly indicate a true/false state or condition.

* Use prefixes like "is", "has", "should", or "can" (e.g., "isValid", "hasPermission").

* Methods returning boolean can also be named as predicates (e.g. "isEmpty()")

**Don't Do This:**

* Use ambiguous names that do not clearly indicate a boolean value.

* Use negative names (e.g., "isNotValid") which can be confusing.

**Why:** Explicit boolean names improve code clarity and prevent misunderstandings about the variable or method's purpose.

**Example:**

"""java

// Good boolean naming

boolean isValidInput = true;

public boolean hasAccess() { ... }

public boolean canProcessOrder() { ... }

// Bad boolean naming

boolean status = true; // Ambiguous

public boolean check() { ... } // should return true or false, but what does it "check"?

"""

## 3. Stylistic Consistency

### 3.1. Consistent Formatting

**Do This:**

* Use a code formatter (e.g., Prettier, ESLint) to enforce consistent formatting rules automatically.

* Configure the formatter to match the project's established style.

* Run the formatter before committing code to ensure consistency.

**Don't Do This:**

* Rely on manual formatting.

* Ignore formatting warnings or errors.

* Allow inconsistent formatting to accumulate.

**Why:** Consistent formatting reduces noise and makes it easier to compare different parts of the codebase, focusing on the logic instead of the style.

### 3.2. Consistent Naming

**Do This:**

* Adhere to a consistent naming convention throughout the project.

* Use a style guide or linter to enforce naming rules.

* Update naming conventions as needed, but apply changes consistently.

**Don't Do This:**

* Mix different naming styles within the same codebase.

* Change naming conventions arbitrarily.

* Ignore naming violations.

**Why:** Consistent naming improves code readability and makes it easier to search for and understand code elements.

### 3.3. Consistent Documentation

**Do This:**

* Use a consistent documentation style (e.g., JSDoc, JavaDoc, Docstrings).

* Document all public classes, methods, and variables.

* Keep documentation up-to-date with code changes.

**Don't Do This:**

* Use inconsistent documentation styles.

* Omit documentation for important code elements.

* Allow documentation to become outdated.

**Why:** Consistent documentation makes it easier for developers to understand and use the code, especially when working in teams or maintaining code over time.

## 4. Clean Code Principles Applied to Style

### 4.1. Single Responsibility Principle (SRP) and Formatting

**Do This:**

* Limit the size of classes and methods so that each has a single, well-defined responsibility.

* Use formatting to highlight the structure of classes and methods, making their responsibilities clear.

**Don't Do This:**

* Create large, monolithic classes or methods with multiple responsibilities.

* Use formatting that obscures the structure and purpose of code.

**Why:** SRP improves code modularity and maintainability. Clear formatting reinforces the principle by visually separating different responsibilities.

**Example:**

"""java

// Good SRP and formatting

public class OrderValidator {

public boolean isValidOrder(Order order) {

return isOrderNotNull(order) && hasValidItems(order.getItems());

}

private boolean isOrderNotNull(Order order) {

return order != null;

}

private boolean hasValidItems(List items) {

return items != null && !items.isEmpty();

}

// Bad SRP

public class OrderValidator {

// multiple responsibilities in one large method

public boolean validateOrder(Order order) {

if (order == null) {

return false;

}

List items = order.getItems();

if (items == null || items.isEmpty()) {

return false;

}

return true;

}

"""

### 4.2. Open/Closed Principle (OCP) and Naming

**Do This:**

* Design classes and methods that are open for extension but closed for modification.

* Use descriptive naming to indicate how code can be extended without changing its core behavior.

**Don't Do This:**

* Modify existing classes or methods directly to add new functionality.

* Use names that imply code is immutable when it can be extended.

**Why:** OCP promotes code stability and reduces the risk of introducing bugs when adding new features. Descriptive naming helps developers understand how to extend code without breaking existing functionality.

### 4.3. Liskov Substitution Principle (LSP) and Style

**Do This:**

* Ensure that derived classes can be substituted for their base classes without altering the correctness of the program.

* Use formatting and naming to clearly indicate the relationship between base and derived classes.

**Don't Do This:**

* Create derived classes that violate the contracts of their base classes.

* Use styles that obscure the inheritance hierarchy.

**Why:** LSP ensures that inheritance is used correctly, preventing unexpected behavior when substituting derived classes for base classes. Clear formatting and naming reinforce the principle by making inheritance relationships transparent.

### 4.4. Dependency Inversion Principle (DIP) and Documentation

**Do This:**

* Depend on abstractions rather than concrete implementations.

* Use documentation to explain the purpose and usage of abstractions, making it easier to switch between different implementations.

**Don't Do This:**

* Depend directly on concrete classes, creating tight coupling.

* Omit documentation for abstractions, making it difficult to understand their purpose.

**Why:** DIP reduces coupling and improves code flexibility. Documentation helps developers understand how to use abstractions, making it easier to switch between different implementations without affecting other parts of the code.

## 5. Modern Approaches and Patterns

### 5.1. Functional Programming Style

**Do This:**

* Use immutable data structures to avoid side effects.

* Write pure functions that always return the same output for the same input.

* Avoid shared state and mutable data.

**Don't Do This:**

* Modify data structures directly.

* Write functions with side effects.

* Rely on shared state and mutable data.

**Why:** Pure functions and immutable data structures improve code predictability and reduce the risk of bugs.

**Example (JavaScript):**

"""javascript

// Functional Style

const add = (x, y) => x + y;

const numbers = [1, 2, 3, 4];

const doubled = numbers.map(x => x * 2); // Create new array instead of modifying existing

// Non-Functional Style

let total = 0; // shared state across the entire application

function addToTotal(x) {

total += x; // side effect: modifying the total

}

"""

### 5.2. Object-Oriented Programming Style

**Do This:**

* Encapsulate data and behavior within classes.

* Use inheritance to model "is-a" relationships.

* Use polymorphism to create flexible and extensible code.

**Don't Do This:**

* Expose internal data directly.

* Create deep inheritance hierarchies.

* Overuse inheritance when composition is more appropriate.

**Why:** Encapsulation protects data integrity, inheritance promotes code reuse, and polymorphism allows code to adapt to different types of objects.

### 5.3. Immutability

**Do This:**

* Use immutable data structures whenever possible.

* Create new objects instead of modifying existing ones.

* Use functional programming techniques to transform immuatble data.

**Don't Do This:**

* Modify objects directly, leading to side effects and unexpected behavior.

**Why:** Immutable data structures simplify debugging, improve thread safety, and make code more predictable.

## 6. Technology-Specific Details

Each programming language has it's own stylistic quirks. Below are a few high level pointers, which might be enhanced as necessary per project basis.

### 6.1. Python

* Follow PEP 8 style guidelines for code formatting.

* Use docstrings to document classes, methods, and modules.

* Use type hints to improve code clarity and catch errors early.

### 6.2. Java

* Follow the Google Java Style Guide or similar established style guide.

* Use JavaDoc to document classes, methods, and fields.

* Use annotations to provide metadata about the code.

### 6.3. JavaScript

* Follow the Airbnb JavaScript Style Guide or similar established style guide.

* Use JSDoc to document functions, classes, and variables.

* Use TypeScript to add static typing to JavaScript code.

### 6.4. C#

* Follow the Microsoft C# Coding Conventions.

* Use XML documentation comments to document classes, methods, and fields.

* Use attributes to provide metadata about the code.

## 7. Conclusion

Adhering to these code style and convention standards is essential for creating clean, maintainable, and collaborative code. By following these guidelines, development teams can reduce cognitive load, improve code readability, and ensure that code is easy to understand and modify. Consistent formatting, meaningful naming, and clear documentation contribute to a codebase that stands the test of time.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Code Style and Conventions Standards for Clean Code

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Angular v19+ Development Standards and Best Practices: A Comprehensive Guide

Reduced code API cost custom prompt Codershortrules

NgRx Signal Store Best Practices

State Management Standards for Clean Code

API Integration Standards for Clean Code