|
| 1 | +--- |
| 2 | +mode: "agent" |
| 3 | +description: "Write a coding standards document for a project using the coding styles from the file(s) and/or folder(s) passed as arguments in the prompt." |
| 4 | +tools: ['createFile', 'editFiles', 'fetch', 'githubRepo', 'search', 'testFailure'] |
| 5 | +--- |
| 6 | + |
| 7 | +# Write Coding Standards From File |
| 8 | + |
| 9 | +Use the existing syntax of the file(s) to establish the standards and style guides for the project. If more than one file or a folder is passed, loop through each file or files in the folder, appending the file's data to temporary memory or a file, then when complete use temporary data as a single instance; as if it were the file name to base the standards and style guideline on. |
| 10 | + |
| 11 | +## Rules and Configuration |
| 12 | + |
| 13 | +Below is a set of quasi-configuration `boolean` and `string[]` variables. Conditions for handling `true`, or other values for each variable are under the level two heading `## Variable and Parameter Configuration Conditions`. |
| 14 | + |
| 15 | +Parameters for the prompt have a text definition. There is one required parameter **`${fileName}`**, and several optional parameters **`${folderName}`**, **`${instructions}`**, and any **`[configVariableAsParameter]`**. |
| 16 | + |
| 17 | +### Configuration Variables |
| 18 | + |
| 19 | +* addStandardsTest = false; |
| 20 | +* addToREADME = false; |
| 21 | +* addToREADMEInsertions = ["atBegin", "middle", "beforeEnd", "bestFitUsingContext"]; |
| 22 | + - Default to **beforeEnd**. |
| 23 | +* createNewFile = true; |
| 24 | +* fetchStyleURL = true; |
| 25 | +* findInconsistencies = true; |
| 26 | +* fixInconsistencies = true; |
| 27 | +* 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"]; |
| 28 | + - For each file in `${newFileName}`, if file does not exist, use that file name and `break`, else continue to next file name of `${newFileName}`. |
| 29 | +* outputSpecToPrompt = false; |
| 30 | +* useTemplate = "verbose"; // or "v" |
| 31 | + - Possible values are `[["v", "verbose"], ["m", "minimal"], ["b", "best fit"], ["custom"]]`. |
| 32 | + - Selects one of the two example templates at the bottom of prompt file under the level two heading `## Coding Standards Templates`, or use another composition that is a better fit. |
| 33 | + - If **custom**, then apply per request. |
| 34 | + |
| 35 | +### Configuration Variables as Prompt Parameters |
| 36 | + |
| 37 | +If any of the variable names are passed to prompt as-is, or as a similar but clearly related text value, then override the default variable value with the value passed to prompt. |
| 38 | + |
| 39 | +### Prompt Parameters |
| 40 | + |
| 41 | +* **fileName** = The name of the file that will be analyzed in terms of: indentation, variable naming, commenting, conditional procedures, functional procedures, and other syntax related data for the coding language of the file. |
| 42 | +* folderName = The name of the folder that will be used to extract data from multiple files into one aggregated dataset that will be analyzed in terms of: indentation, variable naming, commenting, conditional procedures, functional procedures, and other syntax related data for the coding language of the files. |
| 43 | +* instructions = Additional instructions, rules, and procedures that will be provided for unique cases. |
| 44 | +* [configVariableAsParameter] = If passed will override the default state of the configuration variable. Example: |
| 45 | + - useTemplate = If passed will override the configuration `${useTemplate}` default. Values are `[["v", "verbose"], ["m", "minimal"], ["b", "best fit"]]`. |
| 46 | + |
| 47 | +#### Required and Optional Parameters |
| 48 | + |
| 49 | +* **fileName** - required |
| 50 | +* folderName - *optional* |
| 51 | +* instructions - *optional* |
| 52 | +* [configVariableAsParameter] - *optional* |
| 53 | + |
| 54 | +## Variable and Parameter Configuration Conditions |
| 55 | + |
| 56 | +### `${fileName}.length > 1 || ${folderName} != undefined` |
| 57 | + |
| 58 | +* If true, toggle `${fixInconsistencies}` to false. |
| 59 | + |
| 60 | +### `${addToREADME} == true` |
| 61 | + |
| 62 | +* Insert the coding standards into the `README.md` instead of outputting to the prompt or creating a new file. |
| 63 | +* If true, toggle both `${createNewFile}` and `${outputSpecToPrompt}` to false. |
| 64 | + |
| 65 | +### `${addToREADMEInsertions} == "atBegin"` |
| 66 | + |
| 67 | +* If `${addToREADME}` is true, then insert the coding standards data at the **beginning** of the `README.md` file after the title. |
| 68 | + |
| 69 | +### `${addToREADMEInsertions} == "middle"` |
| 70 | + |
| 71 | +* If `${addToREADME}` is true, then insert the coding standards data at the **middle** of the `README.md` file, changing the standards title heading to match that of the `README.md` composition. |
| 72 | + |
| 73 | +### `${addToREADMEInsertions} == "beforeEnd"` |
| 74 | + |
| 75 | +* If `${addToREADME}` is true, then insert the coding standards data at the **end** of the `README.md` file, inserting a new line after the last character, then inserting the data on a new line. |
| 76 | + |
| 77 | +### `${addToREADMEInsertions} == "bestFitUsingContext"` |
| 78 | + |
| 79 | +* If `${addToREADME}` is true, then insert the coding standards data at the **best fitting line** of the `README.md` file in regards to the context of the `README.md` composition and flow of data. |
| 80 | + |
| 81 | +### `${addStandardsTest} == true` |
| 82 | + |
| 83 | +* Once the coding standards file is complete, write a test file to ensure the file or files passed to it adhere to the coding standards. |
| 84 | + |
| 85 | +### `${createNewFile} == true` |
| 86 | + |
| 87 | +* Create a new file using the value, or one of the possible values, from `${newFileName}`. |
| 88 | +* If true, toggle both `${outputSpecToPrompt}` and `${addToREADME}` to false. |
| 89 | + |
| 90 | +### `${fetchStyleURL} == true` |
| 91 | + |
| 92 | +* Additionally use the data fetched from the links nested under level three heading `### Fetch Links` as context for creating standards, specifications, and styling data for the new file, prompt, or `README.md`. |
| 93 | +* For each relevant item in `### Fetch Links`, run `#fetch ${item}`. |
| 94 | + |
| 95 | +### `${findInconsistencies} == true` |
| 96 | + |
| 97 | +* Evaluate syntax related to indentations, line-breaks, comments, conditional and function nesting, quotation wrappers i.e. `'` or `"` for strings, etc., and categorize. |
| 98 | +* For each category, make a count, and if one item does not match the majority of the count, then commit to temporary memory. |
| 99 | +* Depending on the status of `${fixInconsistencies}`, either edit and fix the low count categories to match the majority, or output to prompt inconsistencies stored in temporary memory. |
| 100 | + |
| 101 | +### `${fixInconsistencies} == true` |
| 102 | + |
| 103 | +* Edit and fix the low count categories of syntax data to match the majority of corresponding syntax data using inconsistencies stored in temporary memory. |
| 104 | + |
| 105 | +### `typeof ${newFileName} == "string"` |
| 106 | + |
| 107 | +* If specifically defined as a `string`, create a new file using the value from `${newFileName}`. |
| 108 | + |
| 109 | +### `typeof ${newFileName} != "string"` |
| 110 | + |
| 111 | +* If **NOT** specifically defined as a `string`, but instead an `object` or an array, create a new file using a value from `${newFileName}` by applying this rule: |
| 112 | + - For each file name in `${newFileName}`, if file does not exist, use that file name and `break`, else continue to the next. |
| 113 | + |
| 114 | +### `${outputSpecToPrompt} == true` |
| 115 | + |
| 116 | +* Output the coding standards to the prompt instead of creating a file or adding to README. |
| 117 | +* If true, toggle both `${createNewFile}` and `${addToREADME}` to false. |
| 118 | + |
| 119 | +### `${useTemplate} == "v" || ${useTemplate} == "verbose"` |
| 120 | + |
| 121 | +* Use data under the level three heading `### "v", "verbose"` as guiding template when composing the data for coding standards. |
| 122 | + |
| 123 | +### `${useTemplate} == "m" || ${useTemplate} == "minimal"` |
| 124 | + |
| 125 | +* Use data under the level three heading `### "m", "minimal"` as guiding template when composing the data for coding standards. |
| 126 | + |
| 127 | +### `${useTemplate} == "b" || ${useTemplate} == "best"` |
| 128 | + |
| 129 | +* Use either the data under the level three heading `### "v", "verbose"` or `### "m", "minimal"`, depending on the data extracted from `${fileName}`, and use the best fit as guiding template when composing the data for coding standards. |
| 130 | + |
| 131 | +### `${useTemplate} == "custom" || ${useTemplate} == "<ANY_NAME>"` |
| 132 | + |
| 133 | +* Use the custom prompt, instructions, template, or other data passed as guiding template when composing the data for coding standards. |
| 134 | + |
| 135 | +## **if** `${fetchStyleURL} == true` |
| 136 | + |
| 137 | +Depending on the programming language, for each link in list below, run `#fetch (URL)`, if programming language is `${fileName} == [<Language> Style Guide]`. |
| 138 | + |
| 139 | +### Fetch Links |
| 140 | + |
| 141 | +- [C Style Guide](https://users.ece.cmu.edu/~eno/coding/CCodingStandard.html) |
| 142 | +- [C# Style Guide](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) |
| 143 | +- [C++ Style Guide](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) |
| 144 | +- [Go Style Guide](https://github.com/golang-standards/project-layout) |
| 145 | +- [Java Style Guide](https://coderanch.com/wiki/718799/Style) |
| 146 | +- [AngularJS App Style Guide](https://github.com/mgechev/angularjs-style-guide) |
| 147 | +- [jQuery Style Guide](https://contribute.jquery.org/style-guide/js/) |
| 148 | +- [JavaScript Style Guide](https://www.w3schools.com/js/js_conventions.asp) |
| 149 | +- [JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml) |
| 150 | +- [Kotlin Style Guide](https://kotlinlang.org/docs/coding-conventions.html) |
| 151 | +- [Markdown Style Guide](https://cirosantilli.com/markdown-style-guide/) |
| 152 | +- [Perl Style Guide](https://perldoc.perl.org/perlstyle) |
| 153 | +- [PHP Style Guide](https://phptherightway.com/) |
| 154 | +- [Python Style Guide](https://peps.python.org/pep-0008/) |
| 155 | +- [Ruby Style Guide](https://rubystyle.guide/) |
| 156 | +- [Rust Style Guide](https://github.com/rust-lang/rust/tree/HEAD/src/doc/style-guide/src) |
| 157 | +- [Swift Style Guide](https://www.swift.org/documentation/api-design-guidelines/) |
| 158 | +- [TypeScript Style Guide](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html) |
| 159 | +- [Visual Basic Style Guide](https://en.wikibooks.org/wiki/Visual_Basic/Coding_Standards) |
| 160 | +- [Shell Script Style Guide](https://google.github.io/styleguide/shellguide.html) |
| 161 | +- [Git Usage Style Guide](https://github.com/agis/git-style-guide) |
| 162 | +- [PowerShell Style Guide](https://github.com/PoshCode/PowerShellPracticeAndStyle) |
| 163 | +- [CSS](https://cssguidelin.es/) |
| 164 | +- [Sass Style Guide](https://sass-guidelin.es/) |
| 165 | +- [HTML Style Guide](https://github.com/marcobiedermann/html-style-guide) |
| 166 | +- [Linux kernel Style Guide](https://www.kernel.org/doc/html/latest/process/coding-style.html) |
| 167 | +- [Node.js Style Guide](https://github.com/felixge/node-style-guide) |
| 168 | +- [SQL Style Guide](https://www.sqlstyle.guide/) |
| 169 | +- [Angular Style Guide](https://angular.dev/style-guide) |
| 170 | +- [Vue Style Guide](https://vuejs.org/style-guide/rules-strongly-recommended.html) |
| 171 | +- [Django Style Guide](https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/) |
| 172 | + |
| 173 | +## Coding Standards Templates |
| 174 | + |
| 175 | +### `"m", "minimal"` |
| 176 | + |
| 177 | +```text |
| 178 | + ```markdown |
| 179 | + ## 1. Introduction |
| 180 | + * **Purpose:** Briefly explain why the coding standards are being established (e.g., to improve code quality, maintainability, and team collaboration). |
| 181 | + * **Scope:** Define which languages, projects, or modules this specification applies to. |
| 182 | +
|
| 183 | + ## 2. Naming Conventions |
| 184 | + * **Variables:** `camelCase` |
| 185 | + * **Functions/Methods:** `PascalCase` or `camelCase`. |
| 186 | + * **Classes/Structs:** `PascalCase`. |
| 187 | + * **Constants:** `UPPER_SNAKE_CASE`. |
| 188 | +
|
| 189 | + ## 3. Formatting and Style |
| 190 | + * **Indentation:** Use 4 spaces per indent (or tabs). |
| 191 | + * **Line Length:** Limit lines to a maximum of 80 or 120 characters. |
| 192 | + * **Braces:** Use the "K&R" style (opening brace on the same line) or the "Allman" style (opening brace on a new line). |
| 193 | + * **Blank Lines:** Specify how many blank lines to use for separating logical blocks of code. |
| 194 | +
|
| 195 | + ## 4. Commenting |
| 196 | + * **Docstrings/Function Comments:** Describe the function's purpose, parameters, and return values. |
| 197 | + * **Inline Comments:** Explain complex or non-obvious logic. |
| 198 | + * **File Headers:** Specify what information should be included in a file header, such as author, date, and file description. |
| 199 | +
|
| 200 | + ## 5. Error Handling |
| 201 | + * **General:** How to handle and log errors. |
| 202 | + * **Specifics:** Which exception types to use, and what information to include in error messages. |
| 203 | +
|
| 204 | + ## 6. Best Practices and Anti-Patterns |
| 205 | + * **General:** List common anti-patterns to avoid (e.g., global variables, magic numbers). |
| 206 | + * **Language-specific:** Specific recommendations based on the project's programming language. |
| 207 | +
|
| 208 | + ## 7. Examples |
| 209 | + * Provide a small code example demonstrating the correct application of the rules. |
| 210 | + * Provide a small code example of an incorrect implementation and how to fix it. |
| 211 | +
|
| 212 | + ## 8. Contribution and Enforcement |
| 213 | + * Explain how the standards are to be enforced (e.g., via code reviews). |
| 214 | + * Provide a guide for contributing to the standards document itself. |
| 215 | + ``` |
| 216 | +``` |
| 217 | + |
| 218 | +### `"v", verbose"` |
| 219 | + |
| 220 | +```text |
| 221 | + ```markdown |
| 222 | +
|
| 223 | + # Style Guide |
| 224 | +
|
| 225 | + This document defines the style and conventions used in this project. |
| 226 | + All contributions should follow these rules unless otherwise noted. |
| 227 | +
|
| 228 | + ## 1. General Code Style |
| 229 | +
|
| 230 | + - Favor clarity over brevity. |
| 231 | + - Keep functions and methods small and focused. |
| 232 | + - Avoid repeating logic; prefer shared helpers/utilities. |
| 233 | + - Remove unused variables, imports, code paths, and files. |
| 234 | +
|
| 235 | + ## 2. Naming Conventions |
| 236 | +
|
| 237 | + Use descriptive names. Avoid abbreviations unless well-known. |
| 238 | +
|
| 239 | + | Item | Convention | Example | |
| 240 | + |-----------------|----------------------|--------------------| |
| 241 | + | Variables | `lower_snake_case` | `buffer_size` | |
| 242 | + | Functions | `lower_snake_case()` | `read_file()` | |
| 243 | + | Constants | `UPPER_SNAKE_CASE` | `MAX_RETRIES` | |
| 244 | + | Types/Structs | `PascalCase` | `FileHeader` | |
| 245 | + | File Names | `lower_snake_case` | `file_reader.c` | |
| 246 | +
|
| 247 | + ## 3. Formatting Rules |
| 248 | +
|
| 249 | + - Indentation: **4 spaces** |
| 250 | + - Line length: **max 100 characters** |
| 251 | + - Encoding: **UTF-8**, no BOM |
| 252 | + - End files with a newline |
| 253 | +
|
| 254 | + ### Braces (example in C, adjust for your language) |
| 255 | +
|
| 256 | + ```c |
| 257 | + if (condition) { |
| 258 | + do_something(); |
| 259 | + } else { |
| 260 | + do_something_else(); |
| 261 | + } |
| 262 | + ``` |
| 263 | +
|
| 264 | + ### Spacing |
| 265 | +
|
| 266 | + - One space after keywords: `if (x)`, not `if(x)` |
| 267 | + - One blank line between top-level functions |
| 268 | +
|
| 269 | + ## 4. Comments & Documentation |
| 270 | +
|
| 271 | + - Explain *why*, not *what*, unless intent is unclear. |
| 272 | + - Keep comments up-to-date as code changes. |
| 273 | + - Public functions should include a short description of purpose and parameters. |
| 274 | +
|
| 275 | + Recommended tags: |
| 276 | +
|
| 277 | + ```text |
| 278 | + TODO: follow-up work |
| 279 | + FIXME: known incorrect behavior |
| 280 | + NOTE: non-obvious design decision |
| 281 | + ``` |
| 282 | +
|
| 283 | + ## 5. Error Handling |
| 284 | +
|
| 285 | + - Handle error conditions explicitly. |
| 286 | + - Avoid silent failures; either return errors or log them appropriately. |
| 287 | + - Clean up resources (files, memory, handles) before returning on failure. |
| 288 | +
|
| 289 | + ## 6. Commit & Review Practices |
| 290 | +
|
| 291 | + ### Commits |
| 292 | + - One logical change per commit. |
| 293 | + - Write clear commit messages: |
| 294 | +
|
| 295 | + ```text |
| 296 | + Short summary (max ~50 chars) |
| 297 | + Optional longer explanation of context and rationale. |
| 298 | + ``` |
| 299 | +
|
| 300 | + ### Reviews |
| 301 | + - Keep pull requests reasonably small. |
| 302 | + - Be respectful and constructive in review discussions. |
| 303 | + - Address requested changes or explain if you disagree. |
| 304 | +
|
| 305 | + ## 7. Tests |
| 306 | +
|
| 307 | + - Write tests for new functionality. |
| 308 | + - Tests should be deterministic (no randomness without seeding). |
| 309 | + - Prefer readable test cases over complex test abstraction. |
| 310 | +
|
| 311 | + ## 8. Changes to This Guide |
| 312 | +
|
| 313 | + Style evolves. |
| 314 | + Propose improvements by opening an issue or sending a patch updating this document. |
| 315 | + ``` |
| 316 | +``` |
0 commit comments