bbatsov/clojure-style-guide
Clojure Style Guide
This project provides a set of software architecture guidelines, Lisp coding standards, and functional programming patterns for Clojure development. It establishes best practices for implementing declarative logic and managing shared state through the use of persistent data structures and atomic references.
The guide covers standards for documenting public APIs and organizing project directories to ensure portable library distribution. It details the application of consistent formatting and naming rules to improve source code readability and team collaboration.
The scope extends to idiomatic development patterns, including the organization of namespaces, the structuring of function definitions and test suites, and the responsible design of macros. It also provides guidance on handling interop with external types and managing library distribution via stable coordinates.
Features
- Idiomatic Coding Standards - Provides a comprehensive set of idiomatic conventions and best practices for writing functional Clojure code.
- Functional Programming Patterns - Implements functional programming paradigms including declarative logic, immutable bindings, and atomic state management.
- Lisp Coding Standards - Provides specific guidelines for function definitions, namespace management, and formatting within Lisp environments.
- Persistent Data Structures - Advocates for the use of immutable collections to ensure thread safety and predictable performance.
- Pure Functional Logic Implementations - Implements pure functional logic to create cleaner and more maintainable control flow.
- Atomic State Coordination - Provides guidelines for managing shared state using atomic references and software transactional memory to prevent data corruption.
- Code Formatting Standards - Applies consistent formatting and naming rules to Clojure source code to improve readability and collaboration.
- Concurrent State Coordination - Coordinates shared mutable state across concurrent execution units using atomic references.
- Functional Declarative Patterning - Promotes the use of functional compositions over imperative loops to simplify logic and improve maintainability.
- Project Structure Organization - Defines standards for organizing namespaces and project directories to ensure discoverable and portable library structures.
- Software Architecture Guidelines - Defines best practices for high-level architectural organization, API documentation, and dependency management.
- Software Transactional Memory - Implements concurrency control through software transactional memory to manage shared state atomically.
- Library Publishing - Establishes a publishing pipeline for libraries focusing on stable coordinates and minimal dependencies.
- Foreign Type Wrappers - Defines boundaries and wrappers for foreign collections and constructors to maintain compatibility with native abstractions.
- Language-Level Documentation - Standardizes the use of docstrings and metadata to communicate usage and versioning for public APIs.
- Spacing and Indentation Rules - Enforces consistent indentation and spacing rules to improve source code readability.
- Library Distribution Bundlers - Provides guidelines for selecting stable coordinates and minimizing dependencies to create portable library artifacts.
- Code Commenting - Defines a standardized hierarchy of comment symbols for source code documentation and technical debt tracking.
- Maintenance Constraints - Provides standards for limiting function length and parameter counts to ensure maintainable and testable logic.
- Identifier Naming Conventions - Applies consistent casing and naming conventions to identifiers to signal intent and behavior.
- Namespace Organization - Groups functions and modules into namespaces to prevent naming conflicts and improve discoverability.
- Module Namespaces - Provides a hierarchical naming schema and alias system to organize code and prevent identifier collisions.
- Artifact Coordinate Systems - Guidance on using stable coordinates and versioning to ensure portable library distribution.
- Compositional Macro Design - Establishes best practices for designing complex macros by breaking them into small, testable functions.
- Macro Decompositions - Provides a strategy for creating reliable syntactic macros by decomposing them into testable units.
- API Documentation Annotations - Defines standards for using docstrings and metadata tags to document public APIs.
- Public API Definitions - Establishes processes for defining public interfaces to track compatibility and version increments.
- Source Code Formatting - Standardizes the visual layout of source code, including indentation and spacing rules.
- Application Testing Workflows - Outlines comprehensive strategies for structuring test suites and assertion patterns to ensure long-term maintainability.
- Test Suite Structuring - Provides a standardized directory structure and assertion pattern for implementing automated behavior tests.
- Test Suite Organization - Establishes consistent naming and assertion patterns for structuring manageable and scalable test suites.
- Language Style Guides - Community-driven style guide for writing idiomatic Clojure code.
- Programming Language Standards - Standardized coding style for the Clojure language.
- Learning and Exercises - Community-driven style guide.
