├── .gitignore ├── LICENSE.txt ├── README.md ├── bash-scripts ├── CONVENTIONS.md └── README.md ├── flutter ├── CONVENTIONS.md └── README.md ├── functional-programming ├── CONVENTIONS.md └── README.md ├── golang ├── CONVENTIONS.md └── README.md ├── icalendar-events ├── CONVENTIONS.md └── README.md ├── moodle500 ├── CONVENTIONS.md └── README.md └── nextjs-ts ├── CONVENTIONS.md └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | .aider* 2 | .env 3 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Aider Conventions Repository 2 | 3 | This repository is a collection of community-contributed convention files for use with [aider](https://aider.chat), an AI pair programming tool. Convention files help guide the AI to follow specific coding styles, practices, and preferences. 4 | 5 | ## What are Convention Files? 6 | 7 | Convention files are markdown files that specify coding guidelines for aider to follow. They can include preferences like: 8 | - Coding style rules 9 | - Preferred libraries and packages 10 | - Type hint requirements 11 | - Testing conventions 12 | - Documentation standards 13 | - And more 14 | 15 | For more information about using conventions with aider, see the [conventions documentation](https://aider.chat/docs/usage/conventions.html). 16 | 17 | ## How to Use These Conventions 18 | 19 | 1. Browse the subdirectories to find a conventions file that matches your needs 20 | 2. Copy the desired `CONVENTIONS.md` to your project 21 | 3. Load it in aider using either: 22 | ```bash 23 | aider --read-only CONVENTIONS.md 24 | ``` 25 | Or add it to your `.aider.conf.yml`: 26 | ```yaml 27 | read-only: CONVENTIONS.md 28 | ``` 29 | 30 | ## Directory Structure 31 | 32 | Each subdirectory contains: 33 | - `README.md` - Explains the purpose and use case for the conventions 34 | - `CONVENTIONS.md` - The actual conventions file to use with aider 35 | 36 | ## Contributing 37 | 38 | We welcome contributions! To add your own conventions: 39 | 40 | 1. Create a new subdirectory with a descriptive name 41 | 2. Include both a `README.md` explaining your conventions and a `CONVENTIONS.md` file 42 | 3. Submit a Pull Request 43 | 44 | Please ensure your README.md clearly explains: 45 | - The purpose of your conventions 46 | - What kind of projects they're best suited for 47 | - Any special instructions for using them 48 | 49 | -------------------------------------------------------------------------------- /bash-scripts/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | # When writing bash scripts, you MUST follow these principles 2 | 3 | - Code should be easy to read and understand. 4 | 5 | - Keep the code as simple as possible. Avoid unnecessary complexity. 6 | 7 | - Use meaningful names for variables, functions, etc. Names should reveal intent. 8 | 9 | - Functions should be small and do one thing well. They should not exceed a few lines. 10 | 11 | - Function names should describe the action being performed. 12 | 13 | - Prefer fewer arguments in functions. Ideally, aim for no more than two or three. 14 | 15 | - Only use comments when necessary, as they can become outdated.\ 16 | Instead, strive to make the code self-explanatory. 17 | 18 | - When comments are used, they should add useful information that is not\ 19 | readily apparent from the code itself. 20 | 21 | - Properly handle errors and exceptions to ensure the software's robustness. 22 | 23 | - Consider security implications of the code.\ 24 | Implement security best practices to protect against vulnerabilities and attacks. 25 | 26 | - Executables must start with `#!/usr/bin/env bash` and minimal flags. 27 | 28 | - Use set to set shell options so that calling your script as `bash script_name`\ 29 | does not break its functionality. 30 | 31 | - Shell should only be used for small utilities or simple wrapper scripts. 32 | 33 | - If you are writing a script that is more than 100 lines long, or that uses\ 34 | non-straightforward control flow logic, suggest a rewrite in a more\ 35 | structured language now. 36 | 37 | - Executables should have a .sh extension or no extension. 38 | 39 | - Libraries must have a .sh extension and should not be executable. 40 | 41 | - SUID and SGID are forbidden on shell scripts. 42 | 43 | - All error messages should go to STDERR. 44 | 45 | - Start each file with a description of its contents. 46 | 47 | - Every file must have a top-level comment including a brief overview of its contents. 48 | 49 | - A copyright notice and author information are optional. 50 | 51 | - Any function that is not both obvious and short must have a function header comment.\ 52 | Any function in a library must have a function header comment regardless of\ 53 | length or complexity. 54 | 55 | - It should be possible for someone else to learn how to use your program or\ 56 | to use a function in your library by reading the comments (and self-help,\ 57 | if provided) without reading the code. 58 | 59 | - All function header comments should describe the intended API behaviour. 60 | 61 | - Description of a function includes\ 62 | `Globals: List of global variables used and modified`\ 63 | `Arguments: Arguments taken`,`Outputs: Output to STDOUT or STDERR`\ 64 | `Returns: Returned values other than the default exit status of last command`. 65 | 66 | - Comment tricky, non-obvious, interesting or important parts of your code. 67 | 68 | - Indent 2 spaces. No tabs. 69 | 70 | - Maximum line length is 80 characters. 71 | 72 | - If you have to write literal strings that are longer than 80 characters,\ 73 | this should be done with a here document or an embedded newline if possible. 74 | 75 | - Pipelines should be split one per line if they don’t all fit on one line.\ 76 | If a pipeline all fits on one line, it should be on one line. 77 | 78 | - Put `; then` and `; do` on the same line as the `if`, `for`, or `while`. 79 | 80 | - `else` should be on its own line and closing statements (`fi` and `done`) should be\ 81 | on their own line vertically aligned with the opening statement. 82 | 83 | - Although it is possible to omit `in "$@"` in for loops we recommend consistently\ 84 | including it for clarity. 85 | 86 | - In case statements, indent alternatives by 2 spaces.\ 87 | One-line alternatives need a space after the close parenthesis of the pattern\ 88 | and before the `;;`\ 89 | Long or multi-command alternatives should be split over \ 90 | multiple lines with the pattern, actions, \ 91 | and `;;` on separate lines. 92 | 93 | - In order of precedence: Stay consistent with what you find;\ 94 | quote your variables; prefer `"${var}"` over `"$var"`. 95 | 96 | - Use `"$@"` unless you have a specific reason to use `"$*"`, such as simply\ 97 | appending the arguments to a string in a message or log. 98 | 99 | - Use `$(command)` instead of backticks. 100 | 101 | - `[[…]]` is preferred over `[ … ]`, test and `/usr/bin/[`. 102 | 103 | - Use quotes rather than filler characters where possible. 104 | 105 | - Use an explicit path when doing wildcard expansion of filenames. 106 | 107 | - `eval` should be avoided. 108 | 109 | - Bash arrays should be used to store lists of elements, to avoid quoting\ 110 | complications. This particularly applies to argument lists. 111 | 112 | - Given the choice between invoking a shell builtin and invoking a separate process,\ 113 | choose the builtin. 114 | 115 | - Always check return values and give informative return values. 116 | 117 | - A function called `main` is required for scripts long enough to contain\ 118 | at least one other function. 119 | 120 | - Put all functions together in the file just below constants.\ 121 | Don’t hide executable code between functions.\ 122 | Doing so makes the code difficult to follow and results in nasty surprises \ 123 | when debugging. 124 | 125 | - If you’ve got functions, put them all together near the top of the file.\ 126 | Only includes, set statements and setting constants may be done\ 127 | before declaring functions. 128 | 129 | - Declare function-specific variables with local. Remenber that bash uses dynamic scoping i.e., local variables can be \ 130 | accessed by called functions with the function's body. 131 | 132 | - File names should be lowercase, with underscores to separate words if desired. 133 | 134 | - Constants and anything exported to the environment should be capitalized,\ 135 | separated with underscores, and declared at the top of the file. 136 | 137 | - For the sake of clarity readonly or export is recommended\ 138 | vs. the equivalent declare commands. 139 | 140 | - Aliases should be avoided in scripts. Use functions instead. 141 | 142 | - Always use `(( … ))` or `$(( … ))` rather than `let` or `$[ … ]` or `expr`. 143 | 144 | - Use process substitution or the readarray builtin (bash4+) \ 145 | in preference to piping to while.\ 146 | Pipes create a subshell, so any variables modified within a pipeline\ 147 | do not propagate to the parent shell. 148 | 149 | - Function names should be lower-case, with underscores to separate words.\ 150 | Separate libraries with `::`.\ 151 | Parentheses are required after the function name.\ 152 | The keyword function is optional, but must be used consistently throughout a project. 153 | 154 | - Avoid modifying the values of the following bash variables in a script:\ 155 | `BASH_VERSION`,`BASH_VERSINFO`,`EUID`, `UID`, `PPID`, `PID`, `PGID`, `SID`,\ 156 | `SHLVL`, `RANDOM` ,`LINENO`, `FUNCNAME`, `BASH_SOURCE`, `BASH_LINENO`, `OSTYPE`,\ 157 | `MACHTYPE`, `HOSTTYPE`,`HOSTNAME`,`LINES`, `COLUMNS`,`GROUPS`,`HOME`,`OPTARG`\ 158 | ,`OPTIND`,`REPLY`, `SECONDS`,`TERM`, `DEBUG`. 159 | 160 | - It's worth noting that Bash variables starting with an underscore \ 161 | (e.g., `_`, `__`, etc.) are generally reserved for internal use and should not\ 162 | be modified. 163 | 164 | - When you have a function `main` in the script, wrap the call to `main` as below: 165 | 166 | ```bash 167 | if [[ "${BASH_SOURCE[0]}" == "${0}" ]];then 168 | main "$@" 169 | fi 170 | ``` 171 | 172 | - Every script must have a debug mode that can be enabled from the command line. It can be as simple as `set -x`. 173 | 174 | - For a script that uses complex logic, it is a good practice to provide a dry-run \ 175 | mode with the option enabled from the command line. 176 | 177 | - Complex scripts must provide a verbose mode enabled using -v and --verbose from the command line. When verbose mode \ 178 | is enabled, the script must provide detailed information about its execution, including any errors or warnings. 179 | 180 | - When sourcing a file (say `include.sh`) for a script that may be executed from anywhere, use the following template: 181 | 182 | ```bash 183 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 184 | source "$SCRIPT_DIR/include.sh" 185 | ``` 186 | 187 | - A script's usage must also include examples. 188 | -------------------------------------------------------------------------------- /bash-scripts/README.md: -------------------------------------------------------------------------------- 1 | # Bash Scripts Conventions 2 | 3 | This repository contains conventions and best practices for writing robust, maintainable, and secure Bash scripts. Following these guidelines will help ensure consistency, readability, and reliability across Bash scripts. These conventions are largely influenced by [Google's Shell Style Guide](https://google.github.io/styleguide/shellguide.html) [(web archive in case of broken link)](https://web.archive.org/web/20250320011254/https://google.github.io/styleguide/shellguide.html). 4 | 5 | ## Purpose 6 | 7 | The purpose of this document is to establish a standard for writing Bash scripts by defining best practices for syntax, error handling, security, and readability. 8 | 9 | ## Use Cases 10 | 11 | Ensuring consistency in Bash scripting across projects and teams. 12 | 13 | Writing maintainable scripts that are easy to understand and modify. 14 | 15 | Improving script security by following best practices. 16 | 17 | Reducing errors and unexpected behavior in shell scripts. 18 | 19 | ## Usage 20 | 21 | [See How to Use These Conventions](https://github.com/Aider-AI/conventions#how-to-use-these-conventions) 22 | -------------------------------------------------------------------------------- /flutter/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | # Flutter Development Conventions 2 | 3 | These conventions are designed to ensure a maintainable, readable, and scalable Flutter codebase using the following stack and patterns: 4 | - GetX for state management and navigation 5 | - Dio for HTTP requests 6 | - Material Design 3 for UI (as default) 7 | - Functional programming principles 8 | - Short, modular, and reusable functions 9 | - Clean, readable, and maintainable code 10 | 11 | --- 12 | 13 | ## 1. Separation of Concerns 14 | 15 | - **UI Layer**: Widgets only handle presentation logic. No business logic or direct state manipulation. 16 | - **Controller Layer (GetX Controllers)**: All business logic, state management, and API calls are handled in GetX Controllers. 17 | - **Data Layer**: Data fetching, storage, and transformation logic (repositories, services). 18 | - **Routing Layer**: All navigation must be performed using GetX’s routing system. 19 | 20 | --- 21 | 22 | ## 2. Folder Structure (GetX Pattern) 23 | 24 | ```plaintext 25 | /lib 26 | /core 27 | /theme # Theme management 28 | /utils # Common utilities, extensions, helpers 29 | /network # Dio client and API interceptors, etc. 30 | /data 31 | /models # Data models 32 | /repositories # Data repositories 33 | /modules 34 | /feature_name 35 | /controllers # GetX Controllers 36 | /views # Screens/widgets 37 | /bindings # GetX Bindings for dependency injection 38 | /widgets # Feature-specific widgets 39 | /routes 40 | app_pages.dart # App routes using GetX 41 | main.dart 42 | ``` 43 | 44 | - Each feature/module is self-contained, using GetX’s modular pattern. 45 | 46 | --- 47 | 48 | ## 3. State Management (GetX) 49 | 50 | - Use GetX Controllers for all state and business logic. 51 | - Controllers must be kept lean; delegate logic to services/repositories where possible. 52 | - Use `Obx`/`GetBuilder` only in the UI layer. 53 | - Dispose controllers properly to avoid memory leaks. 54 | 55 | --- 56 | 57 | ## 4. Theme Management 58 | 59 | - Default to Material Design 3 (use `ThemeData(useMaterial3: true)`). 60 | - Centralize all theme and color definitions in `/core/theme`. 61 | - Use GetX to manage dynamic themes (light/dark/system). 62 | 63 | --- 64 | 65 | ## 5. HTTP Requests (Dio) 66 | 67 | - Configure a single Dio client in `/core/network`. 68 | - Use interceptors for logging, error handling, auth, etc. 69 | - All HTTP requests must go through repositories in `/data/repositories`. 70 | - Never call Dio directly from controllers or widgets. 71 | 72 | --- 73 | 74 | ## 6. Functional Programming Principles 75 | 76 | - Prefer pure functions and stateless widgets where possible. 77 | - Avoid shared mutable state. 78 | - Use extension methods for utility logic. 79 | - Functions should be short, modular, and reusable; break down complex logic. 80 | 81 | --- 82 | 83 | ## 7. Code Quality 84 | 85 | - **Short Functions:** Each function should do one thing. Prefer functions under 20 lines. 86 | - **Modular:** Isolate features, logic, and utilities for reuse and testability. 87 | - **Clean Code:** Use descriptive names, avoid magic numbers, document complex logic inline. 88 | - **Readability:** Consistent formatting, avoid deep nesting, prefer early returns. 89 | 90 | --- 91 | 92 | ## 8. UI Guidelines 93 | 94 | - Default to Material Design 3 widgets. 95 | - Avoid third-party UI libraries unless necessary. 96 | - Keep widgets stateless unless local state is required. 97 | - Use custom widgets for repeated UI patterns. 98 | 99 | --- 100 | 101 | ## 9. Example: Feature Module Structure 102 | 103 | ```plaintext 104 | /modules/todo/ 105 | controllers/ 106 | todo_controller.dart 107 | views/ 108 | todo_list_view.dart 109 | todo_detail_view.dart 110 | bindings/ 111 | todo_binding.dart 112 | widgets/ 113 | todo_item.dart 114 | ``` 115 | 116 | --- 117 | 118 | ## 10. Example: Short Modular Functions 119 | 120 | ```dart 121 | // Bad: long, multi-purpose function 122 | void fetchAndDisplayTodos() { 123 | // fetch from API, transform, update UI 124 | } 125 | 126 | // Good: short, reusable functions 127 | Future> fetchTodos() { ... } 128 | List filterTodos(List todos, String query) { ... } 129 | Widget buildTodoList(List todos) { ... } 130 | ``` 131 | 132 | --- 133 | 134 | ## 11. References 135 | 136 | - [GetX Documentation](https://pub.dev/packages/get) 137 | - [Dio Documentation](https://pub.dev/packages/dio) 138 | - [Material 3 Guidelines](https://m3.material.io/) 139 | -------------------------------------------------------------------------------- /flutter/README.md: -------------------------------------------------------------------------------- 1 | # Flutter Conventions 2 | 3 | This repository contains a comprehensive set of conventions for building Flutter applications with a focus on: 4 | 5 | - **Separation of Concerns** 6 | - **GetX for State Management and Routing** 7 | - **Dio for HTTP Requests** 8 | - **Pure Material Design 3 (M3) UI by Default** 9 | - **Functional Programming Principles** 10 | - **Short, Modular, Reusable Functions** 11 | - **Readable, Maintainable, Clean Code** 12 | 13 | ## What’s Inside? 14 | 15 | - [`flutter_conventions.md`](flutter_conventions.md): The main document outlining folder structure, best practices, code organization, and detailed guidelines for using GetX, Dio, and Material 3 in your Flutter projects. 16 | 17 | ## Key Highlights 18 | 19 | - **Folder Structure:** Organize your project using the GetX modular pattern for scalability and maintainability. 20 | - **State Management:** Centralize business logic in GetX Controllers and keep UI pure and presentational. 21 | - **Theme Management:** Use Material 3 and centralize themes for consistency. 22 | - **HTTP Requests:** Perform all API calls via Dio, through repositories, never directly in controllers or widgets. 23 | - **Functional Programming:** Favor pure functions, stateless widgets, and reusable modular code. 24 | - **Code Quality:** Write short, readable, and documented functions for improved maintainability. 25 | 26 | ## Getting Started 27 | 28 | 1. Review [flutter_conventions.md](flutter_conventions.md) and use it as a baseline for all new Flutter projects. 29 | 2. Apply the folder structure and patterns described in the document. 30 | 3. Adhere to the code style and best practices to ensure project consistency. 31 | 32 | ## References 33 | 34 | - [GetX Documentation](https://pub.dev/packages/get) 35 | - [Dio Documentation](https://pub.dev/packages/dio) 36 | - [Material 3 Guidelines](https://m3.material.io/) 37 | 38 | --- 39 | 40 | Feel free to propose improvements or open issues for questions about the conventions. 41 | -------------------------------------------------------------------------------- /functional-programming/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | When writing code, you MUST follow these principles: 2 | - Code should be easy to read and understand. 3 | - Keep the code as simple as possible. Avoid unnecessary complexity. 4 | - Use meaningful names for variables, functions, etc. Names should reveal 5 | intent. 6 | - Functions should be small and do one thing well. They should not exceed a few 7 | lines. 8 | - Function names should describe the action being performed. 9 | - Prefer fewer arguments in functions. Ideally, aim for no more than two or 10 | three. 11 | - Only use comments when necessary, as they can become outdated. Instead, strive 12 | to make the code self-explanatory. 13 | - When comments are used, they should add useful information that is not readily 14 | apparent from the code itself. 15 | - Properly handle errors and exceptions to ensure the software's robustness. 16 | - Use exceptions rather than error codes for handling errors. 17 | - Consider security implications of the code. Implement security best practices 18 | to protect against vulnerabilities and attacks. 19 | - Adhere to these 4 principles of Functional Programming: 20 | 1. Pure Functions 21 | 2. Immutability 22 | 3. Function Composition 23 | 4. Declarative Code 24 | - Do not use object oriented programming. 25 | -------------------------------------------------------------------------------- /functional-programming/README.md: -------------------------------------------------------------------------------- 1 | # Functional Programming Conventions 2 | 3 | This conventions file provides guidelines for writing good functional code. The definition of "good" here is largely influenced by [Clean Code by Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) ([web archive in case of url rot](https://web.archive.org/web/20250127215242/https://www.goodreads.com/book/show/3735293-clean-code)) 4 | 5 | ## Purpose 6 | 7 | These conventions ensure that code is 8 | - simple 9 | - easy to understand 10 | - maintainable 11 | 12 | ## Use Cases 13 | 14 | This convention is intended for use when writing code using functional paradigm 15 | 16 | ## Usage 17 | 18 | [See How to Use These Conventions](https://github.com/Aider-AI/conventions#how-to-use-these-conventions) 19 | -------------------------------------------------------------------------------- /golang/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | # Go (Golang) Development Conventions 2 | 3 | These conventions ensure a scalable, maintainable, and clean Go codebase that prioritizes simplicity, modularity, and readability. They integrate modern Go best practices, including concurrency, error management, and project organization. 4 | 5 | --- 6 | 7 | ## 1. Project Structure 8 | 9 | Use the following pattern for scalable Go applications: 10 | 11 | ```plaintext 12 | /cmd 13 | / # Main application entrypoint(s), minimal logic (calls /internal) 14 | /internal 15 | / # Each domain or feature as a separate module 16 | handlers.go 17 | service.go 18 | repository.go 19 | model.go 20 | /pkg 21 | /utils # Utility functions/libraries for use across modules 22 | /vector # Vector computation helpers (prefer vector ops over loops) 23 | /errors 24 | errors.go # Centralized error definitions and handling 25 | /logging 26 | logger.go # Centralized logging setup and helpers 27 | ``` 28 | 29 | - Place only the main entrypoint in `/cmd//main.go`. 30 | - Keep all implementation logic within `/internal` modules. 31 | - Use `/pkg` for shared libraries and utilities. 32 | - All error handling and logging are centralized. 33 | 34 | --- 35 | 36 | ## 2. Modularity & Simplicity 37 | 38 | - **Single Responsibility:** Every file, type, and function should do one thing. 39 | - **Short Functions:** Keep functions under 30 lines when possible. 40 | - **Descriptive Names:** Use meaningful file, type, and function names (follow [Google Go standards](https://google.github.io/styleguide/go/decisions)). 41 | - **No Printing/Direct Error Handling:** Never log or print errors except via centralized logging and error handling modules. 42 | 43 | --- 44 | 45 | ## 3. Concurrency 46 | 47 | - Use goroutines and channels where suitable (for parallelism and asynchronous tasks). 48 | - Avoid concurrency when it makes code less readable or more complex. 49 | - Prefer vectorized computations (use slices and helper methods in `/pkg/vector`) over manual loops for data processing. 50 | - Always document concurrent code for clarity. 51 | 52 | --- 53 | 54 | ## 4. Error Management 55 | 56 | - **Centralize Errors:** Define all error types and helpers in `/errors/errors.go`. 57 | - **Propagate Errors:** Always return errors to a single handling point, never handle or print errors directly in business logic. 58 | - **Error Wrapping:** Use Go’s error wrapping (`fmt.Errorf("context: %w", err)`) for stack traces. 59 | - **No Silent Failures:** Always check and return errors, never ignore them. 60 | 61 | --- 62 | 63 | ## 5. Logging 64 | 65 | - **Centralized Logging:** Implement all logging in `/logging/logger.go` using a standard Go logger or a third-party package. 66 | - Never log directly in modules; always call the logging package. 67 | - Keep log messages meaningful and context-rich. 68 | 69 | --- 70 | 71 | ## 6. Code Quality 72 | 73 | - **DRY:** Avoid duplication—use helpers or utility packages for repeated logic. 74 | - **Readability:** Prefer clarity over cleverness. Add comments for complex logic. 75 | - **Scalability:** Organize code into modules and packages so new features can be added without major refactoring. 76 | 77 | --- 78 | 79 | ## 7. Naming Conventions 80 | 81 | - File, function, and variable names should be descriptive and follow Go’s camelCase/snake_case conventions. 82 | - No abbreviations except common ones (ctx, err, req, resp, cfg, etc.). 83 | - Use singular names for files and types unless a plural is more semantically correct. 84 | 85 | --- 86 | 87 | ## 8. Example: Error Handling 88 | 89 | ```go 90 | // internal/user/service.go 91 | func (s *Service) GetUser(ctx context.Context, id string) (*User, error) { 92 | user, err := s.repo.FindByID(ctx, id) 93 | if err != nil { 94 | return nil, errors.WrapUserNotFound(err, id) 95 | } 96 | return user, nil 97 | } 98 | 99 | // errors/errors.go 100 | func WrapUserNotFound(err error, id string) error { 101 | return fmt.Errorf("user %s not found: %w", id, err) 102 | } 103 | ``` 104 | 105 | --- 106 | 107 | ## 9. Example: Vector Computation 108 | 109 | ```go 110 | // pkg/vector/vector.go 111 | func Add(a, b []float64) ([]float64, error) { 112 | if len(a) != len(b) { 113 | return nil, errors.New("length mismatch") 114 | } 115 | result := make([]float64, len(a)) 116 | for i := range a { 117 | result[i] = a[i] + b[i] 118 | } 119 | return result, nil 120 | } 121 | ``` 122 | 123 | --- 124 | 125 | ## 10. References 126 | 127 | - [Go Project Layout](https://github.com/golang-standards/project-layout) 128 | - [Google Go Style Guide](https://google.github.io/styleguide/go/decisions) 129 | - [Effective Go](https://go.dev/doc/effective_go) 130 | -------------------------------------------------------------------------------- /golang/README.md: -------------------------------------------------------------------------------- 1 | # Golang Conventions 2 | 3 | This folder provides conventions for building robust, readable, and scalable Go (Golang) applications, focusing on simplicity, modularity, and maintainability. 4 | 5 | ## Key Principles 6 | 7 | - **Project Structure:** Use the `/cmd`, `/internal`, `/pkg`, `/errors`, and `/logging` layout. Keep main logic out of `main.go`. 8 | - **Separation of Concerns:** Each module in `/internal` is responsible for a single feature/domain. 9 | - **Concurrency:** Use goroutines and channels when it improves performance and clarity, but avoid over-complicating code. 10 | - **Vector Computation:** Prefer vectorized operations over explicit looping when possible for data processing. 11 | - **Error & Logging Management:** All errors are propagated and handled in `/errors`; all logging is managed centrally in `/logging`. 12 | - **Code Quality:** Short, single-purpose functions; clear, descriptive names; and code that is easy to maintain and extend. 13 | 14 | ## How To Use 15 | 16 | 1. Review [`golang_conventions.md`](golang_conventions.md) for detailed guidelines and examples. 17 | 2. Organize your repositories and modules as described. 18 | 3. Centralize and standardize all error and logging logic. 19 | 4. Write code that is easy for others to understand and extend. 20 | 21 | ## References 22 | 23 | - [Go Project Layout](https://github.com/golang-standards/project-layout) 24 | - [Google Go Style Guide](https://google.github.io/styleguide/go/decisions) 25 | - [Effective Go](https://go.dev/doc/effective_go) 26 | 27 | --- 28 | 29 | Contributions and suggestions are welcome! 30 | -------------------------------------------------------------------------------- /icalendar-events/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | Rules for turning a set of events with dates and times into an accurate iCalendar .ics file. 2 | 3 | IT IS CRITICAL THAT THE ICS FILE HAS THE CORRECT DATES, TIMES AND TIMEZONES! 4 | 5 | - It's important to fully, accurately turn the provided events into correct iCalendar .ics entries. 6 | - Timezones matter. Include proper local time zones if locations are specified. Ask the user for the relevant timezone(s) if they are unclear. 7 | - Don't assume the year(s) of the events. Ask the user if the year(s) of the events are unclear. 8 | - Multi-day events like hotel stays should be "all day" events, not span continuously from start to end times. 9 | - If the user asks you to proofread or double check: 10 | - Make a text list of all the events as provided and all the iCalendar entries 11 | - Include dates/times/timezones. 12 | - You should point out any errors/problems in the iCalendar .ics file, not ask the user to identify problems. 13 | - At the end, list all errors in the iCalendar .ics file that need to be corrected with explanations. 14 | - Don't critique the itinerary or events, just the accuracy of the iCalendar .ics file. 15 | 16 | Always output a text list of all the events that will go into the calendar. 17 | Ask the user for approval. 18 | Once the user approves, make the iCalendar .ics file. 19 | 20 | 21 | -------------------------------------------------------------------------------- /icalendar-events/README.md: -------------------------------------------------------------------------------- 1 | # iCalendar Events Conventions 2 | 3 | This conventions file provides guidelines for accurately converting event information into iCalendar (.ics) format files. 4 | You can paste random unstructured text or even images/PDFs of events and 5 | itineraries and turn them into iCalendar files suitable for importing 6 | into your calendar tool. 7 | 8 | The best approach is to save your event info to a file and run aider like: 9 | 10 | 11 | ```bash 12 | aider output.ics --read-only my-events.txt --read-only CONVENTIONS.md 13 | 14 | # or 15 | 16 | aider output.ics --read-only my-events.pdf --read-only CONVENTIONS.md 17 | ``` 18 | 19 | You can ask aider to proofread the generated iCalendar file. 20 | But you should personally proofread the results in your Calendar app, 21 | as mistakes can still happen. 22 | Proofreading is usually much easier than tediously creating calendar 23 | entries for a long itinerary. 24 | 25 | ## Purpose 26 | 27 | These conventions ensure that: 28 | - Events are correctly formatted according to iCalendar standards 29 | - Dates, times, and timezones are properly specified 30 | - Multi-day events are handled appropriately 31 | - All necessary event details are captured accurately 32 | 33 | ## Use Cases 34 | 35 | This convention is ideal for: 36 | - Creating calendar files from travel itineraries 37 | - Converting event lists to shareable calendar formats 38 | - Generating conference or meeting schedules 39 | - Planning multi-day events and stays 40 | 41 | ## Usage 42 | 43 | Save your event information to a file, then run aider like: 44 | 45 | ```bash 46 | aider output.ics --read-only my-events.txt --read-only CONVENTIONS.md 47 | 48 | # or 49 | 50 | aider output.ics --read-only my-events.pdf --read-only CONVENTIONS.md 51 | ``` 52 | 53 | Or you can simply paste your event info into the chat. 54 | 55 | The AI will: 56 | - Request any missing critical information 57 | - Create a text list of events for your approval 58 | - Generate the proper iCalendar (.ics) file once approved 59 | -------------------------------------------------------------------------------- /moodle500/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | # Moodle Plugin Development Conventions 2 | 3 | These conventions are used to guide the development of Moodle plugins. 4 | 5 | ### General 6 | 7 | * **HTTP Requests:** Prefer `httpx` over `requests` for making HTTP requests. 8 | * **Type Hints:** Use type hints wherever possible to improve code clarity and maintainability. 9 | 10 | ## Moodle Specific 11 | 12 | * Follow the Moodle coding standards and API documentation: 13 | * [Moodle Architecture](https://docs.moodle.org/dev/Moodle_architecture) 14 | * [Moodle Development Policies](https://moodledev.io/general/development/policies) 15 | * [Moodle Web Service API](https://docs.moodle.org/dev/Web_service_API_functions) 16 | 17 | * Use Moodle's recommended development tools: 18 | * [Node.js](https://moodledev.io/general/development/tools/nodejs) 19 | 20 | ## Moodle Architecture 21 | 22 | * **Modular System:** Moodle is a modular system. Always extend functionality through plugins, not by modifying core files. 23 | * **Plugin Types:** Understand the different plugin types (activities, resources, blocks, themes, etc.) and use the appropriate APIs for each. 24 | * **Core Concepts:** Be aware of core Moodle concepts like courses, activities, users, roles, and permissions. 25 | * **Course Structure:** Courses are sequences of activities and resources grouped into sections. 26 | * **User Roles:** Users have roles (e.g., student, teacher) that define their capabilities within a course or the site. 27 | * **Contexts:** Understand that Moodle uses contexts (e.g., courses, modules, blocks) to manage permissions. 28 | * **Permissions:** Permissions control what users can do in a given context. 29 | * **Database:** Moodle's database is composed of core tables and plugin-specific tables. 30 | * **Database Definitions:** Database structure is defined in `install.xml` files within each plugin's `db` folder. 31 | * **Transaction Script:** Moodle primarily uses a transaction script approach, with core functionality refactored into libraries. 32 | * **Presentation Layer:** Separate presentation from business logic using themes and renderer classes. 33 | * **Upgrade Process:** Moodle can be upgraded in four steps: 34 | 1. Ensure server compatibility. 35 | 2. Create backups and test installations. 36 | 3. Replace Moodle code. 37 | 4. Trigger the upgrade from the admin page. 38 | * **Activity and Resource Plugins:** Activities and resources are the main tools for teaching and learning. 39 | * **Block Plugins:** Blocks provide interface functionality on pages. 40 | * **Theme Plugins:** Themes control the visual style of the Moodle site. 41 | * **Language Packs:** Moodle is internationalized, use language packs for different languages. 42 | * **Course Format Plugins:** Course formats control how the course structure is presented. 43 | * **Authentication Plugins:** Authentication plugins control how users log in. 44 | * **Enrolment Plugins:** Enrolment plugins control which users are enrolled in which courses. 45 | * **Repository Plugins:** Repository plugins provide ways for users to get content into Moodle. 46 | 47 | ## Moodle Development Policies 48 | (from https://moodledev.io/general/development/policies) 49 | 50 | These rules are derived from the Moodle development policies and should be followed when developing Moodle plugins. 51 | 52 | ### General Architecture 53 | 54 | * **Platform Compatibility:** Moodle aims to run on a wide range of platforms. Ensure your code is compatible and portable. 55 | * **Modularity:** Moodle is modular. Extend functionality through plugins, not by modifying core files. 56 | * **Plugin Types:** Understand and use the appropriate plugin types (activities, resources, blocks, themes, etc.) and their APIs. 57 | 58 | ### Coding Style 59 | 60 | * **Consistent Style:** Follow Moodle's coding style to ensure code readability and maintainability. 61 | * **Community Acceptance:** Adhering to the coding style is important for code to be accepted by the Moodle community. 62 | 63 | ### Security 64 | 65 | * **Security Guidelines:** Strictly follow Moodle's security guidelines to protect user data and prevent vulnerabilities. 66 | * **Responsible Internet Citizen:** Ensure your code does not introduce vulnerabilities that could compromise the server. 67 | 68 | #### Standards 69 | 70 | * **HTML5 Compliance:** Produce strict, well-formed HTML5 code, preferably backwards compatible with XHTML 1.1. 71 | * **Accessibility:** Comply with common accessibility guidelines (W3C WCAG 2.0, ARIA). 72 | * **CSS for Layout:** Use CSS for layout and separate presentation from business logic. 73 | * **Theme Extension:** If creating a custom theme, extend the Moodle 'Boost' theme. 74 | 75 | #### JavaScript 76 | 77 | * **Vanilla JavaScript:** Write new JavaScript in Vanilla JavaScript using ES6 style. 78 | * **Discourage Frameworks:** Avoid using jQuery, YUI, and other frameworks except for legacy interfaces. 79 | * **Avoid Interface Manipulation:** Write code to avoid removing or adding interfaces as the page loads. 80 | * **Accessibility:** Ensure all JavaScript is accessible. 81 | 82 | #### Internationalisation 83 | 84 | * **Language Packs:** Keep language strings and locale information separate from the code, using language packs. 85 | * **Default Language:** Use English (AU) as the default language for all code, comments, and documentation. 86 | 87 | #### Accessibility 88 | 89 | * **Wide Range of Users:** Ensure Moodle works well for the widest possible range of people. 90 | 91 | #### Component Library 92 | 93 | * **Component Reuse:** Utilize the component library to identify and reuse frequently-used user interface components. 94 | 95 | #### Performance 96 | 97 | * **Scalability:** Ensure your code scales well with an increasing number of users, courses, and activities. 98 | * **Discourage Performance Issues:** Avoid features that are discouraged on production sites for performance reasons. 99 | 100 | #### Database 101 | 102 | * **XMLDB:** Use Moodle's database abstraction layer (XMLDB) for database interactions. 103 | * **Database APIs:** Use the provided tools and APIs for defining, modifying, retrieving, and storing data. 104 | 105 | #### Events 106 | 107 | * **Event Observers:** Use event observers to be notified when events happen and act on the data. 108 | * **Observer Limitations:** Observers cannot modify event data or prevent actions from occurring. 109 | * **Naming Convention:** Follow the events naming convention. 110 | 111 | #### Web Services 112 | 113 | * **Web Service API:** Implement web services according to the Web Service API functions. 114 | * **Naming Convention:** Follow the naming convention for web service functions. 115 | 116 | #### Testing 117 | 118 | * **Manual Testing:** Write clear testing instructions for manual testing. 119 | * **Unit Testing:** Create automated unit tests for each bit of functionality using PHPUnit. 120 | * **Acceptance Testing:** Automate user interaction testing using the Behat framework. 121 | 122 | #### Third Party Libraries 123 | 124 | * **Standard Inclusion:** Use the standard way to include third-party libraries in your code. 125 | 126 | #### Other Standards 127 | 128 | * **Unique Style:** Moodle coding style is unique and not compatible with PEAR or other common PHP standards. 129 | 130 | #### Translations 131 | 132 | * **Internationalization:** Pay attention to keeping the language strings and locale information separate from the code, in language packs. 133 | 134 | ## Bootstrap 5 Migration 135 | 136 | These rules are derived from the Bootstrap 5 migration guide and should be followed when updating Moodle's UI. 137 | 138 | ### General Migration 139 | 140 | * **Gradual Migration:** The migration to Bootstrap 5 will be done in a gradual way, with steps executed in different phases. 141 | * **PopperJS Upgrade:** Upgrade PopperJS to version 2, while maintaining compatibility with version 1 for Bootstrap 4. 142 | * **SCSS Deprecation:** Follow the SCSS deprecation process for cleanup after the Bootstrap 5 upgrade. 143 | * **Refactor BS4 Features:** Refactor Bootstrap 4 features that are deprecated or dropped in Bootstrap 5. 144 | * **BS5 Bridge:** Use a BS5 "bridge" to address simple breaking changes in advance. 145 | * **BS5 Upgrade:** Upgrade the current Bootstrap 4 version to version 5. 146 | * **BS4 Backwards-Compatibility:** Create a backwards-compatibility layer to allow Bootstrap 4 syntax to still work until final deprecation. 147 | * **Final Deprecation:** Eventually, fully deprecate Bootstrap 4 syntax. 148 | 149 | ### Refactoring BS4 Features 150 | 151 | * **Badge Colors:** Replace `.badge-*` color classes with background utilities like `.bg-primary` and corresponding text color classes (`.text-dark` or `.text-white`). 152 | * **Badge Pills:** Replace `.badge-pill` with `.rounded-pill`. 153 | * **Media Component:** Replace the `.media` component with utility classes like `d-flex`, `flex-shrink-0`, and `flex-grow-1`. 154 | * **Mixins:** Refactor deprecated mixins such as `hover`, `float-left`, `nav-divider`, `img-retina`, `text-hide`, `invisible`, `form-control-focus`, `text-emphasis-variant`, `size`, `make-container-max-widths`, `g-variant`, and `bg-gradient-variant`. Use the suggested replacements. 155 | * **Form Groups:** Replace `.form-group` with margin utilities. 156 | * **Form Inline:** Replace `.form-inline` with utility classes like `d-flex` and `flex-wrap`. 157 | * **Card Decks:** Replace `.card-deck` with utility classes like `row` and `col`. 158 | 159 | ### BS5 Bridge 160 | 161 | * **SCSS Bridge File:** Use the `bs5-bridge.scss` file in `theme/boost/scss/moodle` for compatibility changes. 162 | * **No Gutters:** Replace `.no-gutters` with `.g-0`. 163 | * **Close Button:** Replace `.close` with `.btn-close`. 164 | * **Directional Utilities:** 165 | * Replace `.float-left` and `.float-right` with `.float-start` and `.float-end`. 166 | * Replace `.border-left` and `.border-right` with `.border-start` and `.border-end`. 167 | * Replace `.rounded-left` and `.rounded-right` with `.rounded-start` and `.rounded-end`. 168 | * Replace `.ml-*` and `.mr-*` with `.ms-*` and `.me-*`. 169 | * Replace `.pl-*` and `.pr-*` with `.ps-*` and `.pe-*`. 170 | * Replace `.text-left` and `.text-right` with `.text-start` and `.text-end`. 171 | * **Theme Color Level:** Replace `theme-color-level()` with `shift-color()`, using percentages instead of levels (e.g., level 1 becomes 10%). 172 | * **Rounded Classes:** Replace `.rounded-sm` and `.rounded-lg` with `.rounded-1` and `.rounded-3`. 173 | * **Screen Reader Utilities:** 174 | * Replace `.sr-only` and `.sr-only-focusable` with `.visually-hidden` and `.visually-hidden-focusable`. 175 | * Replace `sr-only()` and `sr-only-focusable()` mixins with `visually-hidden()` and `visually-hidden-focusable()`. 176 | * **Font Utility Classes:** 177 | * Replace `.font-weight-*` with `.fw-*`. 178 | * Replace `.font-italic` with `.fst-italic`. 179 | 180 | ## Aider JavaScript Rules for Moodle Plugin Development 181 | 182 | These rules are derived from the Moodle JavaScript guidelines and are intended to guide Aider in generating Moodle-compliant JavaScript code. 183 | 184 | #### General 185 | 186 | - **ES2015+ Modules:** All new JavaScript code must use ES2015+ module format, which is transpiled into CommonJS format. 187 | - **RequireJS Loader:** Modules are loaded in the browser using the RequireJS loader. 188 | - **Moodle Features:** Use Moodle's Mustache templates, translated strings, and web service framework. 189 | - **Vanilla JavaScript:** Use vanilla JavaScript with Moodle helpers, avoiding jQuery, YUI, and other frameworks except for legacy interfaces. 190 | - **Accessibility:** Ensure all JavaScript is accessible. 191 | 192 | ##### Module Structure 193 | 194 | - **Naming Convention:** JavaScript modules must follow the naming convention: `[component_name]/[optional/sub/namespace/][modulename]`. 195 | - **Component Directory:** The first directory in any subfolder must be either a Moodle API or `local`. 196 | - **Examples:** 197 | - `mod_forum/discussion` 198 | - `mod_assign/grades/grader` 199 | - `block_newsitems/local/modal/confirmation` 200 | - `core_user/local/participants/selectors` 201 | - **Subdirectories:** Create a main entry-point module with related modules in a subdirectory. 202 | - Example: `core_user/participants` with submodules in `local/participants`. 203 | - `local/participants/repository.js` (module name: `core_user/local/participants/repository`) 204 | - `local/participants/selectors.js` (module name: `core_user/local/participants/selectors`) 205 | - `participants.js` (module name: `core_user/participants`) 206 | 207 | ##### Module Content 208 | 209 | - **Entry Point:** Each module should have an entry point, usually a function called `init`, which is exported. 210 | - **Dependencies:** Import dependencies using the `import` keyword. 211 | - **Exports:** Export functions, objects, classes, and other data structures as needed. 212 | 213 | ##### DOM Event Handling 214 | 215 | - **Event Listeners:** Use `document.addEventListener()` to listen for DOM events. 216 | - **CSS Selectors:** Store CSS selectors in a separate `Selectors` object within the module. 217 | - **Data Attributes:** Use `data-*` attributes to identify elements for event listeners. 218 | - **Namespaces:** Use namespaces for `data-action` attributes to identify the purpose of the button. 219 | - **Event Delegation:** Use event delegation to handle events on multiple elements with a single listener. 220 | - **`e.target.closest()`:** Use `e.target.closest()` to check if the clicked element or its parent matches a CSS selector. 221 | 222 | ##### Including JavaScript 223 | 224 | - **From Templates:** Use `{{#js}}` tags in Mustache templates to include JavaScript. 225 | - Example: 226 | ```html 227 | {{#js}} 228 | require(['mod_forum/discussion'], function(Discussion) { 229 | Discussion.init(); 230 | }); 231 | {{/js}} 232 | ``` 233 | - Use `{{uniqid}}` to generate unique IDs for DOM elements and pass them to the module. 234 | - **From PHP:** Use `$PAGE->requires->js_call_amd()` to include JavaScript from PHP. 235 | - Example: `$PAGE->requires->js_call_amd('mod_forum/discussion', 'init');` 236 | - Pass arguments to the function as an array: `$PAGE->requires->js_call_amd('mod_forum/discussion', 'init', [$course->id]);` 237 | - Use array destructuring in JavaScript to get named values from multi-dimensional arrays. 238 | 239 | ##### Data Handling 240 | 241 | - **Data Attributes:** Use `data-*` attributes to pass data to JavaScript modules. 242 | - **Web Services:** Use Moodle Web Services to fetch complex data structures dynamically. 243 | 244 | ##### Promises 245 | 246 | - **`then` and `catch`:** Use `then` and `catch` consistently for promise handling. 247 | - **Return Promises:** Return a Promise from a function if the function is primarily tasked with creating that Promise. 248 | - **Avoid `done`, `fail`, `always`:** Do not use `done`, `fail`, or `always` functions on Promises. 249 | 250 | ##### Strings 251 | 252 | - **`core/str` Module:** Use the `core/str` module to fetch and render language strings. 253 | - **`getString`:** Use `getString` to fetch a single string (returns a native Promise). 254 | - **`getStrings`:** Use `getStrings` to fetch a set of strings (returns an array of native Promises). 255 | - **`get_string`:** Use `get_string` to fetch a single string (returns a jQuery Promise, for legacy support). 256 | - **`get_strings`:** Use `get_strings` to fetch a set of strings (returns an array of jQuery Promises, for legacy support). 257 | - **Caching:** Strings are cached in LocalStorage. 258 | - **Native Promises:** Prefer `getString` and `getStrings` from Moodle 4.3 onwards. 259 | 260 | ##### Prefetching 261 | 262 | - **`core/prefetch` Module:** Use the `core/prefetch` module to prefetch assets. 263 | - **`prefetchString`:** Prefetch a single string. 264 | - **`prefetchStrings`:** Prefetch multiple strings. 265 | - **`prefetchTemplate`:** Prefetch a single template. 266 | - **`prefetchTemplates`:** Prefetch multiple templates. 267 | 268 | ##### Dropzone 269 | 270 | - **`core/dropzone` Module:** Use the `core/dropzone` module to create drop zones. 271 | - **Accessibility:** The module ensures accessibility requirements are met. 272 | - **Callbacks:** Drop zones trigger callbacks for common actions. 273 | 274 | ##### Reactive State 275 | 276 | - **Framework Independence:** Core developments are framework independent. 277 | - **Ad-hoc Library:** Moodle implements a basic reactive state pattern using an ad-hoc library. 278 | 279 | ##### Tools 280 | 281 | - **NodeJS:** Most Moodle JavaScript tooling requires NodeJS. 282 | - **Grunt:** Use Grunt to compile JavaScript and CSS, and to lint JavaScript, CSS, and Behat tests. 283 | - `npm -g install grunt-cli` 284 | - `npx grunt` or `grunt` 285 | - **ESLint:** Use ESLint for JavaScript linting. 286 | 287 | ## Aider JavaScript Rules for Moodle AJAX 288 | 289 | These rules are derived from the Moodle AJAX guidelines and are intended to guide Aider in generating Moodle-compliant JavaScript code for AJAX interactions. 290 | 291 | ## General 292 | 293 | - **`core/ajax` Module:** Use the `core/ajax` JavaScript module for all new AJAX interactions. 294 | - **Web Service API:** AJAX calls should directly call web service functions built using the Moodle Web Service API. 295 | - **Security:** Web service functions used for AJAX must be marked as available for AJAX in `db/services.php` by defining `'ajax' => true`. 296 | - **Single HTTP Request:** Multiple web service requests can be chained in a single HTTP request. 297 | - **Type Checking:** Ensure strict type checking for all parameters and return types in web service functions. 298 | 299 | #### Design Patterns 300 | 301 | - **Repository Module:** Place all code using the `core/ajax` module into a single `repository.js` file within the component's `amd/src` directory. 302 | - **Meaningful Responses:** Each web service call should have a meaningful response. 303 | - **Chained Calls:** Use `core/ajax` to make multiple web service calls from a single transaction. 304 | - **Import `call`:** Import the `call` function from `core/ajax` as `fetchMany`. 305 | - **Export Functions:** Export functions from the repository module that encapsulate specific web service calls. 306 | - **Call Web Services:** Call the exported functions from other modules to initiate AJAX requests. 307 | 308 | #### Key Considerations 309 | 310 | - **Templates:** Use Moodle templates to update parts of the UI in response to AJAX changes. 311 | - **Theme Context:** When calling `$PAGE->get_renderer()` in a web service, ensure the correct theme is set, potentially by passing the theme as a parameter to the web service. 312 | - **Text Filtering:** Filter text returned from a web service using `external_format_text` or `external_format_string` with the correct context. 313 | - **Context Specificity:** Use the most specific context relating to the output when filtering text. 314 | - **Filter Notification:** After adding dynamic content to a page, notify Moodle's filters via `M.core.event.FILTER_CONTENT_UPDATED`. 315 | - **Web Service Updates:** After adding or changing any web service definition in `db/services.php`, bump the plugin or Moodle version number and run the upgrade. 316 | - **Safe Web Services:** Mark web services as safe to call without a session only if they return 100% public information and do not consume many resources. 317 | - Add `'loginrequired' => false` to the service definition in `db/services.php`. 318 | - Pass `false` as the third argument to the `call` method when calling the web service. 319 | 320 | #### Code Examples 321 | 322 | ### Repository Module 323 | 324 | ```javascript 325 | import {call as fetchMany} from 'core/ajax'; 326 | 327 | export const submitGradingForm = ( 328 | assignmentid, 329 | userid, 330 | data, 331 | ) => fetchMany([{ 332 | methodname: 'mod_assign_submit_grading_form', 333 | args: { 334 | assignmentid, 335 | userid, 336 | jsonform JSON.stringify(data), 337 | }, 338 | }])[0]; 339 | ``` 340 | 341 | ### Calling the Web Service 342 | 343 | ```javascript 344 | import {submitGradingForm} from './repository'; 345 | 346 | export const doSomething = async() => { 347 | // ... 348 | const assignmentId = getAssigmentId(); 349 | const getUserId = getUserId(); 350 | const data = getData(); 351 | 352 | const response = await submitGradingForm(assignmentId, userId, data); 353 | window.console.log(response); 354 | } 355 | ``` 356 | 357 | ### Chained Calls 358 | 359 | ```javascript 360 | import {call as fetchMany} from 'core/ajax'; 361 | 362 | const getGradingFormRequest = (assignmentid, userid, data) => ({ 363 | methodname: 'mod_assign_submit_grading_form', 364 | args: { 365 | assignmentid, 366 | userid, 367 | jsonform JSON.stringify(data), 368 | }, 369 | }); 370 | 371 | const getNextGraderRequest = (assignmentid, userid) => ({ 372 | methodname: 'mod_assign_get_grading_form', 373 | args: { 374 | assignmentid, 375 | userid, 376 | }, 377 | }); 378 | 379 | export const submitGradingFormAndFetchNext = ( 380 | assignmentId, 381 | currentUserId, 382 | currentUserData, 383 | nextUserId 384 | ) => { 385 | const responses = fetchMany([ 386 | getGradingFormRequest(assignmentId, usecurrentUserIdrId, currentUserData), 387 | getNextGraderRequest(assignmentId, nextUserId), 388 | ]); 389 | 390 | return { 391 | submittedGradingForm: responses[0], 392 | nextGradingForm: responses[1], 393 | }; 394 | }; 395 | ``` 396 | 397 | ### Calling Chained Web Services 398 | 399 | ```javascript 400 | import {submitGradingFormAndFetchNext} from './repository'; 401 | 402 | export const doSomething = async() => { 403 | // ... 404 | const assignmentId = getAssigmentId(); 405 | const getUserId = getUserId(); 406 | const data = getData(); 407 | 408 | const { 409 | submittedGradingForm, 410 | nextGradingForm, 411 | } = submitGradingFormAndFetchNext(assignmentId, userId, data, getNextuserId); 412 | window.console.log(await submittedGradingForm); 413 | window.console.log(await nextGradingForm); 414 | } 415 | ``` 416 | 417 | ## Frankenstyle Component Naming Rules 418 | 419 | These rules define how to name components in Moodle, following the "Frankenstyle" convention. 420 | 421 | ### General Format 422 | 423 | Frankenstyle component names are constructed with a prefix and a folder name, separated by an underscore: `prefix_foldername`. 424 | 425 | 1. **Prefix:** Determined by the plugin type (e.g., `mod` for activity modules). 426 | 2. **Folder Name:** The plugin's folder name, always in lowercase (e.g., `quiz`). 427 | 428 | Example: The frankenstyle name for the quiz module is `mod_quiz`. 429 | 430 | ### Plugin Type Prefixes 431 | 432 | Refer to the [Plugin types](https://docs.moodle.org/dev/Plugin_types) page for a comprehensive list of plugin types and their corresponding prefixes. 433 | 434 | ### Core Subsystems 435 | 436 | Core subsystems use the format `core_subsystemname`. 437 | 438 | Here's a list of core subsystems and their frankenstyle names: 439 | 440 | - Access: `core_access` 441 | - Administration: `core_admin` 442 | - Antivirus: `core_antivirus` 443 | - Authentication: `core_auth` 444 | - Conditional availability: `core_availability` 445 | - Backup and restore: `core_backup` 446 | - Badges: `core_badges` 447 | - Blocks: `core_block` 448 | - Blogging: `core_blog` 449 | - Bulk users operations: `core_bulkusers` 450 | - Caching: `core_cache` 451 | - Calendar: `core_calendar` 452 | - Cohorts: `core_cohort` 453 | - Comment: `core_comment` 454 | - Competency based education: `core_competency` 455 | - Completion: `core_completion` 456 | - Countries: `core_countries` 457 | - Course: `core_course` 458 | - Currencies: `core_currencies` 459 | - Database transfer: `core_dbtransfer` 460 | - Debugging: `core_debug` 461 | - Text editors: `core_editor` 462 | - Education fields: `core_edufields` 463 | - Enrol: `core_enrol` 464 | - Error reporting: `core_error` 465 | - Favourites: `core_favourites` 466 | - File picker: `core_filepicker` 467 | - Files management: `core_files` 468 | - User filtering: `core_filters` 469 | - Forms: `core_form` 470 | - Grades: `core_grades` 471 | - Advanced grading: `core_grading` 472 | - Groups: `core_group` 473 | - Help: `core_help` 474 | - Hub: `core_hub` 475 | - IMS CC: `core_imscc` 476 | - Installer: `core_install` 477 | - ISO 6392: `core_iso6392` 478 | - Language pack configuration: `core_langconfig` 479 | - License: `core_license` 480 | - Maths library: `core_mathslib` 481 | - Media: `core_media` 482 | - Messaging: `core_message` 483 | - MIME types: `core_mimetypes` 484 | - MNet: `core_mnet` 485 | - Dashboard: `core_my` 486 | - User notes: `core_notes` 487 | - Page types: `core_pagetype` 488 | - Pictures and icons: `core_pix` 489 | - Plagiarism: `core_plagiarism` 490 | - Plugins management: `core_plugin` 491 | - Portfolio: `core_portfolio` 492 | - Privacy: `core_privacy` 493 | - Course publishing: `core_publish` 494 | - Question bank engine: `core_question` 495 | - Ratings: `core_rating` 496 | - Site registration: `core_register` 497 | - Repository: `core_repository` 498 | - RSS: `core_rss` 499 | - Roles: `core_role` 500 | - Global search: `core_search` 501 | - Tabular data display/download (deprecated): `core_table` 502 | - Tagging: `core_tag` 503 | - Timezones: `core_timezones` 504 | - User: `core_user` 505 | - User key: `core_userkey` 506 | - Web service: `core_webservice` 507 | 508 | ### Usage Rules 509 | 510 | #### Function Names 511 | 512 | - All plugin functions must start with the full frankenstyle prefix. 513 | - Activity modules may also use `modulename_` as a prefix for backward compatibility. 514 | - Avoid global functions; use autoloaded classes instead. 515 | 516 | #### Class Names 517 | 518 | - Place all component classes in the `classes` directory. 519 | - Use namespaces based on the frankenstyle component name. 520 | - Example: A discussion class in the forum activity should be in the `mod_forum` namespace and may have a class name of `discussion` - `\mod_forum\discussion`. 521 | - Avoid non-namespaced classes using only the frankenstyle prefix. 522 | 523 | #### Constants 524 | 525 | - All plugin constants must start with an uppercase frankenstyle prefix (e.g., `MOD_FORUM_XXXX`). 526 | - Use class constants on autoloaded classes instead of global constants where possible. 527 | 528 | #### Table Names 529 | 530 | - All table names for a plugin must begin with its frankenstyle name (after the standard Moodle table prefix). 531 | - Exception: Moodle activities do not have the `mod_` prefix in table names (for historical reasons). 532 | - Examples: 533 | - `local_coolreport` 534 | - `local_coolreport_users` 535 | - `forum` (for the `mod_forum` component) 536 | 537 | #### Plugin Configuration Table 538 | 539 | - In the `config_plugins` table, the `plugin` column uses the frankenstyle name. 540 | 541 | #### Capabilities 542 | 543 | - All capabilities for a plugin use the frankenstyle name, with `/` instead of `_`. 544 | - Examples: 545 | - `mod/quiz:viewattempt` 546 | - `block/library:readbook` 547 | 548 | #### Language Files 549 | 550 | - The main language file for each plugin (except activity modules) is named after the frankenstyle component name. 551 | - Examples: 552 | - `/blocks/participants/lang/en/block_participants.php` 553 | - `/mod/quiz/lang/en/quiz.php` 554 | 555 | #### Other places 556 | 557 | - `@package` declarations in phpdocs 558 | - Web service function names 559 | - Moodle Plugins database 560 | - JS module names 561 | - Template names 562 | 563 | ### Theme Name Variants 564 | 565 | - When creating a theme that is a derivative of another theme, avoid including the parent theme's name in the new theme's name. 566 | 567 | ### See Also 568 | 569 | - [Plugins](https://docs.moodle.org/dev/Plugins) 570 | - [Subplugins](https://docs.moodle.org/dev/Subplugins) 571 | - [Core APIs](https://docs.moodle.org/dev/Core_APIs) 572 | - [Automatic class loading](https://docs.moodle.org/dev/Automatic_class_loading) 573 | -------------------------------------------------------------------------------- /moodle500/README.md: -------------------------------------------------------------------------------- 1 | # Aider-Powered Moodle Plugin Development Conventions 2 | 3 | These conventions help you develop high-quality, reliable Moodle plugins for Moodle 5.0 using Aider. They ensure your plugins adhere to Moodle's coding standards, promote best practices, and streamline the development process. 4 | 5 | ## Purpose 6 | 7 | These conventions ensure: 8 | 9 | * **High-Quality Plugins:** By enforcing coding standards and best practices, these conventions help you create robust, maintainable, and secure Moodle plugins. 10 | * **Moodle Standards Compliance:** Your plugins will adhere to Moodle's coding and API standards, ensuring compatibility and maintainability. 11 | * **Faster Development:** By providing clear guidelines, these conventions help you leverage Aider to accelerate your Moodle plugin development. 12 | 13 | ## Use Cases 14 | 15 | * **New Plugin Development:** Use these conventions when starting a new Moodle plugin project to ensure consistency and efficiency. 16 | * **Aider Integration:** These conventions guide Aider in generating Moodle plugin code that adheres to best practices. 17 | * **Accelerated Development:** These conventions are designed for developers who want to leverage Aider to speed up their Moodle plugin development while maintaining high standards. 18 | 19 | ## Getting Started 20 | 21 | These conventions are designed to be used with Aider. When developing a Moodle plugin, Aider will use these conventions to generate code that adheres to Moodle's standards. 22 | 23 | To get started: 24 | 25 | 1. Ensure you have Aider set up and configured. 26 | 2. Refer to the `CONVENTIONS.md` file for the specific coding and API standards. 27 | 3. Use Aider to generate your Moodle plugin code, and it will automatically apply these conventions. 28 | 29 | ## Contributing 30 | 31 | If you would like to contribute to these conventions, please submit a pull request with your proposed changes. 32 | 33 | ## License 34 | 35 | GPL 3.0 36 | -------------------------------------------------------------------------------- /nextjs-ts/CONVENTIONS.md: -------------------------------------------------------------------------------- 1 | You are a Senior Front-End Developer and an Expert in ReactJS, NextJS, TypeScript, HTML, CSS and modern UI/UX frameworks (e.g., Material UI, Radix, tremor) and NPM runtime and package manager. You are thoughtful, give nuanced answers, and are brilliant at reasoning. You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning. 2 | 3 | - Follow the user’s requirements carefully & to the letter. 4 | - First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail. 5 | - Confirm, then write code! 6 | - Always write correct, best practice, DRY principle (Dont Repeat Yourself), bug free, fully functional and working code also it should be aligned to listed rules down below at Code Implementation Guidelines . 7 | - Focus on easy and readability code, over being performant. 8 | - Fully implement all requested functionality. 9 | - Leave NO todo’s, placeholders or missing pieces. 10 | - Ensure code is complete! Verify thoroughly finalised. 11 | - Include all required imports, and ensure proper naming of key components. 12 | - Be concise Minimize any other prose. 13 | - If you think there might not be a correct answer, you say so. 14 | - If you do not know the answer, say so, instead of guessing. 15 | 16 | ### Coding Environment 17 | 18 | The user asks questions about the following coding languages: 19 | 20 | - ReactJS 21 | - NextJS 22 | - TypeScript 23 | - HTML 24 | - CSS 25 | 26 | ### Code Implementation Guidelines 27 | 28 | Follow these rules when you write code: 29 | 30 | - Use early returns whenever possible to make the code more readable. 31 | - Always use Material UI components for styling HTML elements; avoid using CSS or tags. 32 | - Use descriptive variable and function/const names. Also, event functions should be named with a “handle” prefix, like “handleClick” for onClick and “handleKeyDown” for onKeyDown. 33 | - Implement accessibility features on elements. For example, a tag should have a tabindex=“0”, aria-label, on:click, and on:keydown, and similar attributes. 34 | - Use consts instead of functions, for example, “const toggle = () =>”. Also, define a type if possible. 35 | -------------------------------------------------------------------------------- /nextjs-ts/README.md: -------------------------------------------------------------------------------- 1 | # Next.js TypeScript Conventions 2 | 3 | This conventions file provides guidelines for writing high-quality Next.js applications with TypeScript. The conventions emphasize best practices for modern React development with a focus on accessibility, readability, and maintainability. 4 | 5 | ## Purpose 6 | 7 | These conventions ensure that code is: 8 | - Accessible to all users 9 | - Easy to read and maintain 10 | - Consistent in style and structure 11 | - Following modern React and TypeScript best practices 12 | 13 | ## Use Cases 14 | 15 | This convention is intended for use when developing: 16 | - Next.js applications 17 | - React applications with TypeScript 18 | - Modern web applications requiring strong UI/UX principles 19 | - Projects using Material UI or other component libraries 20 | 21 | ## Usage 22 | 23 | [See How to Use These Conventions](https://github.com/Aider-AI/conventions#how-to-use-these-conventions) 24 | --------------------------------------------------------------------------------