write-coding-standards-from-file

从文件编写编码规范

使用文件的现有语法来为项目建立标准和风格指南。如果传入了多个文件或一个文件夹，则遍历该文件或文件夹中的每个文件，将文件数据追加到临时内存或文件中，然后在完成时将临时数据作为单个实例使用；就好像它就是用于建立标准和风格指南所依据的文件名一样。

规则与配置

以下是一组准配置的 boolean 和 string[] 变量。对每个变量处理 true 或其他值的条件位于二级标题 ## 变量与参数配置条件 下。

提示词的参数有文本定义。有一个必需参数 ${fileName}，以及若干可选参数 ${folderName}、${instructions} 和任意 [configVariableAsParameter]。

配置变量

• addStandardsTest = false;
• addToREADME = false;
• addToREADMEInsertions = ["atBegin", "middle", "beforeEnd", "bestFitUsingContext"];
  • 默认为 beforeEnd。
• createNewFile = true;
• fetchStyleURL = true;
• findInconsistencies = true;
• fixInconsistencies = true;
• newFileName = ["CONTRIBUTING.md", "STYLE.md", "CODE_OF_CONDUCT.md", "CODING_STANDARDS.md", "DEVELOPING.md", "CONTRIBUTION_GUIDE.md", "GUIDELINES.md", "PROJECT_STANDARDS.md", "BEST_PRACTICES.md", "HACKING.md"];
  • 对于 ${newFileName} 中的每个文件，如果文件不存在，则使用该文件名并 break，否则继续 ${newFileName} 中的下一个文件名。
• outputSpecToPrompt = false;
• useTemplate = "verbose"; // or "v"
  • 可能的值有 [["v", "verbose"], ["m", "minimal"], ["b", "best fit"], ["custom"]]。
  • 选择提示词文件底部二级标题 ## 编码规范模板 下两个示例模板之一，或使用另一种更合适的组合。
  • 如果为 custom，则按请求应用。

作为提示词参数的配置变量

如果任何变量名按原样传递给提示词，或作为类似但明显相关的文本值传递，则用传递给提示词的值覆盖默认变量值。

提示词参数

• fileName = 将被分析的文件的名称，分析内容包括：缩进、变量命名、注释、条件流程、函数流程，以及该文件所用编程语言的其他语法相关数据。
• folderName = 将被用于从多个文件提取数据、汇总为一个聚合数据集的文件夹的名称，该数据集将被分析的内容包括：缩进、变量命名、注释、条件流程、函数流程，以及这些文件所用编程语言的其他语法相关数据。
• instructions = 针对特殊情形提供的附加说明、规则和流程。
• [configVariableAsParameter] = 如果传入，将覆盖配置变量的默认状态。示例：
  • useTemplate = 如果传入，将覆盖配置 ${useTemplate} 的默认值。值为 [["v", "verbose"], ["m", "minimal"], ["b", "best fit"]]。

必需参数和可选参数

• fileName - 必需
• folderName - 可选
• instructions - 可选
• [configVariableAsParameter] - 可选

变量与参数配置条件

${fileName}.length > 1 || ${folderName} != undefined

• 如果为 true，则将 ${fixInconsistencies} 切换为 false。

${addToREADME} == true

• 将编码规范插入 README.md，而不是输出到提示词或创建新文件。
• 如果为 true，则同时将 ${createNewFile} 和 ${outputSpecToPrompt} 切换为 false。

${addToREADMEInsertions} == "atBegin"

• 如果 ${addToREADME} 为 true，则将编码规范数据插入到 README.md 文件开头标题之后。

${addToREADMEInsertions} == "middle"

• 如果 ${addToREADME} 为 true，则将编码规范数据插入到 README.md 文件的中间，并将规范标题改为与 README.md 的组成结构相匹配的标题。

${addToREADMEInsertions} == "beforeEnd"

• 如果 ${addToREADME} 为 true，则将编码规范数据插入到 README.md 文件的末尾，在最后一个字符后插入一个换行符，然后在新行插入数据。

${addToREADMEInsertions} == "bestFitUsingContext"

• 如果 ${addToREADME} 为 true，则根据 README.md 的组成结构和数据流，将编码规范数据插入到 README.md 文件的最合适的行中。

${addStandardsTest} == true

• 编码规范文件完成后，编写一个测试文件，以确保传入该文件的一个或多个文件符合编码规范。

${createNewFile} == true

• 使用 ${newFileName} 的值或其中一个可能的值创建一个新文件。
• 如果为 true，则将 ${outputSpecToPrompt} 和 ${addToREADME} 都切换为 false。

${fetchStyleURL} == true

• 另外，使用从三级标题 ### Fetch Links 下嵌套的链接中获取的数据作为上下文，为新文件、提示词或 README.md 创建规范、规格和样式数据。
• 对于 ### Fetch Links 中的每个相关项，运行 #fetch ${item}。

${findInconsistencies} == true

• 评估与缩进、换行、注释、条件与函数嵌套、引号包裹（即字符串使用 ' 或 "）等相关的语法，并进行分类。
• 对于每个类别，进行计数，如果某一项与计数中的多数不匹配，则提交到临时内存。
• 根据 ${fixInconsistencies} 的状态，要么编辑并修复低计数类别以匹配多数，要么将存储在临时内存中的不一致项输出到提示词。

${fixInconsistencies} == true

• 使用存储在临时内存中的不一致项，编辑并修复低计数类别的语法数据，使其匹配对应语法数据的多数。

typeof ${newFileName} == "string"

• 如果明确定义为 string，则使用 ${newFileName} 的值创建一个新文件。

typeof ${newFileName} != "string"

• 如果未明确定义为 string，而是 object 或数组，则应用以下规则使用 ${newFileName} 中的一个值创建新文件：
  • 对于 ${newFileName} 中的每个文件名，如果文件不存在，则使用该文件名并 break，否则继续下一个。

${outputSpecToPrompt} == true

• 将编码规范输出到提示词，而不是创建文件或添加到 README。
• 如果为 true，则将 ${createNewFile} 和 ${addToREADME} 都切换为 false。

${useTemplate} == "v" || ${useTemplate} == "verbose"

• 在编写编码规范数据时，使用三级标题 ### "v", "verbose" 下的数据作为指导模板。

${useTemplate} == "m" || ${useTemplate} == "minimal"

• 在编写编码规范数据时，使用三级标题 ### "m", "minimal" 下的数据作为指导模板。

${useTemplate} == "b" || ${useTemplate} == "best"

• 根据从 ${fileName} 中提取的数据，使用三级标题 ### "v", "verbose" 或 ### "m", "minimal" 下的数据，并选择最匹配的作为指导模板来编写编码规范数据。

${useTemplate} == "custom" || ${useTemplate} == "<ANY_NAME>"

• 使用传入的自定义提示词、指令、模板或其他数据作为指导模板来编写编码规范数据。

if ${fetchStyleURL} == true

根据编程语言，对于以下列表中的每个链接，如果编程语言是 ${fileName} == [<Language> Style Guide]，则运行 #fetch (URL)。

获取链接

• C 风格指南
• C# 风格指南
• C++ 风格指南
• Go 风格指南
• Java 风格指南
• AngularJS 应用风格指南
• jQuery 风格指南
• JavaScript 风格指南
• JSON 风格指南
• Kotlin 风格指南
• Markdown 风格指南
• Perl 风格指南
• PHP 风格指南
• Python 风格指南
• Ruby 风格指南
• Rust 风格指南
• Swift 风格指南
• TypeScript 风格指南
• Visual Basic 风格指南
• Shell 脚本风格指南
• Git 使用风格指南
• PowerShell 风格指南
• CSS
• Sass 风格指南
• HTML 风格指南
• Linux 内核风格指南
• Node.js 风格指南
• SQL 风格指南
• Angular 风格指南
• Vue 风格指南
• Django 风格指南
• SystemVerilog 风格指南

编码规范模板

"m", "minimal"

    ```markdown
    ## 1. Introduction
    *   **Purpose:** Briefly explain why the coding standards are being established (e.g., to improve code quality, maintainability, and team collaboration).
    *   **Scope:** Define which languages, projects, or modules this specification applies to.

    ## 2. Naming Conventions
    *   **Variables:** `camelCase`
    *   **Functions/Methods:** `PascalCase` or `camelCase`.
    *   **Classes/Structs:** `PascalCase`.
    *   **Constants:** `UPPER_SNAKE_CASE`.

    ## 3. Formatting and Style
    *   **Indentation:** Use 4 spaces per indent (or tabs).
    *   **Line Length:** Limit lines to a maximum of 80 or 120 characters.
    *   **Braces:** Use the "K&R" style (opening brace on the same line) or the "Allman" style (opening brace on a new line).
    *   **Blank Lines:** Specify how many blank lines to use for separating logical blocks of code.

    ## 4. Commenting
    *   **Docstrings/Function Comments:** Describe the function's purpose, parameters, and return values.
    *   **Inline Comments:** Explain complex or non-obvious logic.
    *   **File Headers:** Specify what information should be included in a file header, such as author, date, and file description.

    ## 5. Error Handling
    *   **General:** How to handle and log errors.
    *   **Specifics:** Which exception types to use, and what information to include in error messages.

    ## 6. Best Practices and Anti-Patterns
    *   **General:** List common anti-patterns to avoid (e.g., global variables, magic numbers).
    *   **Language-specific:** Specific recommendations based on the project's programming language.

    ## 7. Examples
    *   Provide a small code example demonstrating the correct application of the rules.
    *   Provide a small code example of an incorrect implementation and how to fix it.

    ## 8. Contribution and Enforcement
    *   Explain how the standards are to be enforced (e.g., via code reviews).
    *   Provide a guide for contributing to the standards document itself.
    ```

"v", verbose"

    ```markdown

    # Style Guide

    This document defines the style and conventions used in this project.
    All contributions should follow these rules unless otherwise noted.

    ## 1. General Code Style

    - Favor clarity over brevity.
    - Keep functions and methods small and focused.
    - Avoid repeating logic; prefer shared helpers/utilities.
    - Remove unused variables, imports, code paths, and files.

    ## 2. Naming Conventions

    Use descriptive names. Avoid abbreviations unless well-known.

    | Item            | Convention           | Example            |
    |-----------------|----------------------|--------------------|
    | Variables       | `lower_snake_case`   | `buffer_size`      |
    | Functions       | `lower_snake_case()` | `read_file()`      |
    | Constants       | `UPPER_SNAKE_CASE`   | `MAX_RETRIES`      |
    | Types/Structs   | `PascalCase`         | `FileHeader`       |
    | File Names      | `lower_snake_case`   | `file_reader.c`    |

    ## 3. Formatting Rules

    - Indentation: **4 spaces**
    - Line length: **max 100 characters**
    - Encoding: **UTF-8**, no BOM
    - End files with a newline

    ### Braces (example in C, adjust for your language)

        ```c
        if (condition) {
            do_something();
        } else {
            do_something_else();
        }
        ```

    ### Spacing

    - One space after keywords: `if (x)`, not `if(x)`
    - One blank line between top-level functions

    ## 4. Comments & Documentation

    - Explain *why*, not *what*, unless intent is unclear.
    - Keep comments up-to-date as code changes.
    - Public functions should include a short description of purpose and parameters.

    Recommended tags:

        ```text
        TODO: follow-up work
        FIXME: known incorrect behavior
        NOTE: non-obvious design decision
        ```

    ## 5. Error Handling

    - Handle error conditions explicitly.
    - Avoid silent failures; either return errors or log them appropriately.
    - Clean up resources (files, memory, handles) before returning on failure.

    ## 6. Commit & Review Practices

    ### Commits
    - One logical change per commit.
    - Write clear commit messages:

        ```text
        Short summary (max ~50 chars)
        Optional longer explanation of context and rationale.
        ```

    ### Reviews
    - Keep pull requests reasonably small.
    - Be respectful and constructive in review discussions.
    - Address requested changes or explain if you disagree.

    ## 7. Tests

    - Write tests for new functionality.
    - Tests should be deterministic (no randomness without seeding).
    - Prefer readable test cases over complex test abstraction.

    ## 8. Changes to This Guide

    Style evolves.
    Propose improvements by opening an issue or sending a patch updating this document.
    ```