bbatsov/clojure-style-guide
Clojure Style Guide
该项目为 Clojure 开发提供了一套软件架构指南、Lisp 编码标准和函数式编程模式。它确立了通过使用持久数据结构和原子引用来实现声明式逻辑和管理共享状态的最佳实践。
该指南涵盖了记录公共 API 和组织项目目录的标准，以确保可移植的库分发。它详细说明了应用一致的格式化和命名规则，以提高源代码可读性和团队协作。
其范围扩展到惯用开发模式，包括命名空间的组织、函数定义和测试套件的结构，以及宏的负责任设计。它还提供了关于处理与外部类型的互操作以及通过稳定坐标管理库分发的指导。
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 Guides - Community-accepted style guide for Clojure programming.
- Programming Language Standards - Standardized coding style for the Clojure language.
- Learning and Exercises - Community-driven style guide.
