Enhance Go development instructions with additional best practices an… (#271)
* Enhance Go development instructions with additional best practices and guidelines * node update-readme.js * Enhance Go development instructions with additional clarity on self-documenting code and comment practices * Enhance package declaration guidelines in Go instructions to prevent duplicate declarations and ensure proper naming conventions * Update WaitGroup usage instructions for Go 1.25 to include new Go method syntax * Enhance Go development instructions by emphasizing the use of early return patterns to improve code clarity
This commit is contained in:
sauran
GitHub
parent
a09e74243f
commit
e20b67fe24
@ -24,7 +24,6 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
|
|||||||
| [Epic Product Requirements Document (PRD) Prompt](prompts/breakdown-epic-pm.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-pm.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-pm.prompt.md) | Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification. |
|
| [Epic Product Requirements Document (PRD) Prompt](prompts/breakdown-epic-pm.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-pm.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-epic-pm.prompt.md) | Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification. |
|
||||||
| [Feature Implementation Plan Prompt](prompts/breakdown-feature-implementation.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md) | Prompt for creating detailed feature implementation plans, following Epoch monorepo structure. |
|
| [Feature Implementation Plan Prompt](prompts/breakdown-feature-implementation.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-implementation.prompt.md) | Prompt for creating detailed feature implementation plans, following Epoch monorepo structure. |
|
||||||
| [Feature PRD Prompt](prompts/breakdown-feature-prd.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. |
|
| [Feature PRD Prompt](prompts/breakdown-feature-prd.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-feature-prd.prompt.md) | Prompt for creating Product Requirements Documents (PRDs) for new features, based on an Epic. |
|
||||||
| [GitHub Copilot Starter](prompts/github-copilot-starter.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack |
|
|
||||||
| [GitHub Issue Planning & Project Automation Prompt](prompts/breakdown-plan.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. |
|
| [GitHub Issue Planning & Project Automation Prompt](prompts/breakdown-plan.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-plan.prompt.md) | Issue Planning and Automation prompt that generates comprehensive project plans with Epic > Feature > Story/Enabler > Test hierarchy, dependencies, priorities, and automated tracking. |
|
||||||
| [Test Planning & Quality Assurance Prompt](prompts/breakdown-test.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. |
|
| [Test Planning & Quality Assurance Prompt](prompts/breakdown-test.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fbreakdown-test.prompt.md) | Test Planning and Quality Assurance prompt that generates comprehensive test strategies, task breakdowns, and quality validation plans for GitHub projects. |
|
||||||
| [Clojure Memory Updater](prompts/clojure-add-to-memory.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fclojure-add-to-memory.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fclojure-add-to-memory.prompt.md) | Have the agent update the clojure-memory.instructions.md file with mistakes it just made, or lessons learned. Also consider installing the default clojure-memory.instructions.md |
|
| [Clojure Memory Updater](prompts/clojure-add-to-memory.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fclojure-add-to-memory.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fclojure-add-to-memory.prompt.md) | Have the agent update the clojure-memory.instructions.md file with mistakes it just made, or lessons learned. Also consider installing the default clojure-memory.instructions.md |
|
||||||
@ -66,6 +65,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
|
|||||||
| [Product Manager Assistant: Feature Identification and Specification](prompts/gen-specs-as-issues.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md) | This workflow guides you through a systematic approach to identify missing features, prioritize them, and create detailed specifications for implementation. |
|
| [Product Manager Assistant: Feature Identification and Specification](prompts/gen-specs-as-issues.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgen-specs-as-issues.prompt.md) | This workflow guides you through a systematic approach to identify missing features, prioritize them, and create detailed specifications for implementation. |
|
||||||
| [Migration and Code Evolution Instructions Generator](prompts/generate-custom-instructions-from-codebase.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgenerate-custom-instructions-from-codebase.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgenerate-custom-instructions-from-codebase.prompt.md) | Migration and code evolution instructions generator for GitHub Copilot. Analyzes differences between two project versions (branches, commits, or releases) to create precise instructions allowing Copilot to maintain consistency during technology migrations, major refactoring, or framework version upgrades. |
|
| [Migration and Code Evolution Instructions Generator](prompts/generate-custom-instructions-from-codebase.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgenerate-custom-instructions-from-codebase.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgenerate-custom-instructions-from-codebase.prompt.md) | Migration and code evolution instructions generator for GitHub Copilot. Analyzes differences between two project versions (branches, commits, or releases) to create precise instructions allowing Copilot to maintain consistency during technology migrations, major refactoring, or framework version upgrades. |
|
||||||
| [Git Flow Branch Creator](prompts/git-flow-branch-creator.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. |
|
| [Git Flow Branch Creator](prompts/git-flow-branch-creator.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgit-flow-branch-creator.prompt.md) | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. |
|
||||||
|
| [React Development Guidelines](prompts/github-copilot-starter.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fgithub-copilot-starter.prompt.md) | Set up complete GitHub Copilot configuration for a new project based on technology stack |
|
||||||
| [Java Documentation (Javadoc) Best Practices](prompts/java-docs.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. |
|
| [Java Documentation (Javadoc) Best Practices](prompts/java-docs.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-docs.prompt.md) | Ensure that Java types are documented with Javadoc comments and follow best practices for documentation. |
|
||||||
| [JUnit 5+ Best Practices](prompts/java-junit.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md) | Get best practices for JUnit 5 unit testing, including data-driven tests |
|
| [JUnit 5+ Best Practices](prompts/java-junit.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-junit.prompt.md) | Get best practices for JUnit 5 unit testing, including data-driven tests |
|
||||||
| [Spring Boot Best Practices](prompts/java-springboot.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) | Get best practices for developing applications with Spring Boot. |
|
| [Spring Boot Best Practices](prompts/java-springboot.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md)<br />[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fjava-springboot.prompt.md) | Get best practices for developing applications with Spring Boot. |
|
||||||
|
|||||||
@ -14,9 +14,15 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Follow the principle of least surprise
|
- Follow the principle of least surprise
|
||||||
- Keep the happy path left-aligned (minimize indentation)
|
- Keep the happy path left-aligned (minimize indentation)
|
||||||
- Return early to reduce nesting
|
- Return early to reduce nesting
|
||||||
|
- Prefer early return over if-else chains; use `if condition { return }` pattern to avoid else blocks
|
||||||
- Make the zero value useful
|
- Make the zero value useful
|
||||||
|
- Write self-documenting code with clear, descriptive names
|
||||||
- Document exported types, functions, methods, and packages
|
- Document exported types, functions, methods, and packages
|
||||||
- Use Go modules for dependency management
|
- Use Go modules for dependency management
|
||||||
|
- Leverage the Go standard library instead of reinventing the wheel (e.g., use `strings.Builder` for string concatenation, `filepath.Join` for path construction)
|
||||||
|
- Prefer standard library solutions over custom implementations when functionality exists
|
||||||
|
- Write comments in English by default; translate only upon user request
|
||||||
|
- Avoid using emoji in code and comments
|
||||||
|
|
||||||
## Naming Conventions
|
## Naming Conventions
|
||||||
|
|
||||||
@ -28,6 +34,21 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Avoid generic names like `util`, `common`, or `base`
|
- Avoid generic names like `util`, `common`, or `base`
|
||||||
- Package names should be singular, not plural
|
- Package names should be singular, not plural
|
||||||
|
|
||||||
|
#### Package Declaration Rules (CRITICAL):
|
||||||
|
- **NEVER duplicate `package` declarations** - each Go file must have exactly ONE `package` line
|
||||||
|
- When editing an existing `.go` file:
|
||||||
|
- **PRESERVE** the existing `package` declaration - do not add another one
|
||||||
|
- If you need to replace the entire file content, start with the existing package name
|
||||||
|
- When creating a new `.go` file:
|
||||||
|
- **BEFORE writing any code**, check what package name other `.go` files in the same directory use
|
||||||
|
- Use the SAME package name as existing files in that directory
|
||||||
|
- If it's a new directory, use the directory name as the package name
|
||||||
|
- Write **exactly one** `package <name>` line at the very top of the file
|
||||||
|
- When using file creation or replacement tools:
|
||||||
|
- **ALWAYS verify** the target file doesn't already have a `package` declaration before adding one
|
||||||
|
- If replacing file content, include only ONE `package` declaration in the new content
|
||||||
|
- **NEVER** create files with multiple `package` lines or duplicate declarations
|
||||||
|
|
||||||
### Variables and Functions
|
### Variables and Functions
|
||||||
|
|
||||||
- Use mixedCaps or MixedCaps (camelCase) rather than underscores
|
- Use mixedCaps or MixedCaps (camelCase) rather than underscores
|
||||||
@ -61,12 +82,16 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
|
|
||||||
### Comments
|
### Comments
|
||||||
|
|
||||||
- Write comments in complete sentences
|
- Strive for self-documenting code; prefer clear variable names, function names, and code structure over comments
|
||||||
|
- Write comments only when necessary to explain complex logic, business rules, or non-obvious behavior
|
||||||
|
- Write comments in complete sentences in English by default
|
||||||
|
- Translate comments to other languages only upon specific user request
|
||||||
- Start sentences with the name of the thing being described
|
- Start sentences with the name of the thing being described
|
||||||
- Package comments should start with "Package [name]"
|
- Package comments should start with "Package [name]"
|
||||||
- Use line comments (`//`) for most comments
|
- Use line comments (`//`) for most comments
|
||||||
- Use block comments (`/* */`) sparingly, mainly for package documentation
|
- Use block comments (`/* */`) sparingly, mainly for package documentation
|
||||||
- Document why, not what, unless the what is complex
|
- Document why, not what, unless the what is complex
|
||||||
|
- Avoid emoji in comments and code
|
||||||
|
|
||||||
### Error Handling
|
### Error Handling
|
||||||
|
|
||||||
@ -105,11 +130,14 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Use struct tags for JSON, XML, database mappings
|
- Use struct tags for JSON, XML, database mappings
|
||||||
- Prefer explicit type conversions
|
- Prefer explicit type conversions
|
||||||
- Use type assertions carefully and check the second return value
|
- Use type assertions carefully and check the second return value
|
||||||
|
- Prefer generics over unconstrained types; when an unconstrained type is truly needed, use the predeclared alias `any` instead of `interface{}` (Go 1.18+)
|
||||||
|
|
||||||
### Pointers vs Values
|
### Pointers vs Values
|
||||||
|
|
||||||
- Use pointers for large structs or when you need to modify the receiver
|
- Use pointer receivers for large structs or when you need to modify the receiver
|
||||||
- Use values for small structs and when immutability is desired
|
- Use value receivers for small structs and when immutability is desired
|
||||||
|
- Use pointer parameters when you need to modify the argument or for large structs
|
||||||
|
- Use value parameters for small structs and when you want to prevent modification
|
||||||
- Be consistent within a type's method set
|
- Be consistent within a type's method set
|
||||||
- Consider the zero value when choosing pointer vs value receivers
|
- Consider the zero value when choosing pointer vs value receivers
|
||||||
|
|
||||||
@ -125,7 +153,8 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
|
|
||||||
### Goroutines
|
### Goroutines
|
||||||
|
|
||||||
- Don't create goroutines in libraries; let the caller control concurrency
|
- Be cautious about creating goroutines in libraries; prefer letting the caller control concurrency
|
||||||
|
- If you must create goroutines in libraries, provide clear documentation and cleanup mechanisms
|
||||||
- Always know how a goroutine will exit
|
- Always know how a goroutine will exit
|
||||||
- Use `sync.WaitGroup` or channels to wait for goroutines
|
- Use `sync.WaitGroup` or channels to wait for goroutines
|
||||||
- Avoid goroutine leaks by ensuring cleanup
|
- Avoid goroutine leaks by ensuring cleanup
|
||||||
@ -143,8 +172,17 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Use `sync.Mutex` for protecting shared state
|
- Use `sync.Mutex` for protecting shared state
|
||||||
- Keep critical sections small
|
- Keep critical sections small
|
||||||
- Use `sync.RWMutex` when you have many readers
|
- Use `sync.RWMutex` when you have many readers
|
||||||
- Prefer channels over mutexes when possible
|
- Choose between channels and mutexes based on the use case: use channels for communication, mutexes for protecting state
|
||||||
- Use `sync.Once` for one-time initialization
|
- Use `sync.Once` for one-time initialization
|
||||||
|
- WaitGroup usage by Go version:
|
||||||
|
- If `go >= 1.25` in `go.mod`, use the new `WaitGroup.Go` method ([documentation](https://pkg.go.dev/sync#WaitGroup)):
|
||||||
|
```go
|
||||||
|
var wg sync.WaitGroup
|
||||||
|
wg.Go(task1)
|
||||||
|
wg.Go(task2)
|
||||||
|
wg.Wait()
|
||||||
|
```
|
||||||
|
- If `go < 1.25`, use the classic `Add`/`Done` pattern
|
||||||
|
|
||||||
## Error Handling Patterns
|
## Error Handling Patterns
|
||||||
|
|
||||||
@ -172,6 +210,9 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Use middleware for cross-cutting concerns
|
- Use middleware for cross-cutting concerns
|
||||||
- Set appropriate status codes and headers
|
- Set appropriate status codes and headers
|
||||||
- Handle errors gracefully and return appropriate error responses
|
- Handle errors gracefully and return appropriate error responses
|
||||||
|
- Router usage by Go version:
|
||||||
|
- If `go >= 1.22`, prefer the enhanced `net/http` `ServeMux` with pattern-based routing and method matching
|
||||||
|
- If `go < 1.22`, use the classic `ServeMux` and handle methods/paths manually (or use a third-party router when justified)
|
||||||
|
|
||||||
### JSON APIs
|
### JSON APIs
|
||||||
|
|
||||||
@ -181,6 +222,15 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Consider using `json.RawMessage` for delayed parsing
|
- Consider using `json.RawMessage` for delayed parsing
|
||||||
- Handle JSON errors appropriately
|
- Handle JSON errors appropriately
|
||||||
|
|
||||||
|
### HTTP Clients
|
||||||
|
|
||||||
|
- Keep the client struct focused on configuration and dependencies only (e.g., base URL, `*http.Client`, auth, default headers). It must not store per-request state
|
||||||
|
- Do not store or cache `*http.Request` inside the client struct, and do not persist request-specific state across calls; instead, construct a fresh request per method invocation
|
||||||
|
- Methods should accept `context.Context` and input parameters, assemble the `*http.Request` locally (or via a short-lived builder/helper created per call), then call `c.httpClient.Do(req)`
|
||||||
|
- If request-building logic is reused, factor it into unexported helper functions or a per-call builder type; never keep `http.Request` (URL params, body, headers) as fields on the long-lived client
|
||||||
|
- Ensure the underlying `*http.Client` is configured (timeouts, transport) and is safe for concurrent use; avoid mutating `Transport` after first use
|
||||||
|
- Always set headers on the request instance you’re sending, and close response bodies (`defer resp.Body.Close()`), handling errors appropriately
|
||||||
|
|
||||||
## Performance Optimization
|
## Performance Optimization
|
||||||
|
|
||||||
### Memory Management
|
### Memory Management
|
||||||
@ -191,6 +241,33 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Preallocate slices when size is known
|
- Preallocate slices when size is known
|
||||||
- Avoid unnecessary string conversions
|
- Avoid unnecessary string conversions
|
||||||
|
|
||||||
|
### I/O: Readers and Buffers
|
||||||
|
|
||||||
|
- Most `io.Reader` streams are consumable once; reading advances state. Do not assume a reader can be re-read without special handling
|
||||||
|
- If you must read data multiple times, buffer it once and recreate readers on demand:
|
||||||
|
- Use `io.ReadAll` (or a limited read) to obtain `[]byte`, then create fresh readers via `bytes.NewReader(buf)` or `bytes.NewBuffer(buf)` for each reuse
|
||||||
|
- For strings, use `strings.NewReader(s)`; you can `Seek(0, io.SeekStart)` on `*bytes.Reader` to rewind
|
||||||
|
- For HTTP requests, do not reuse a consumed `req.Body`. Instead:
|
||||||
|
- Keep the original payload as `[]byte` and set `req.Body = io.NopCloser(bytes.NewReader(buf))` before each send
|
||||||
|
- Prefer configuring `req.GetBody` so the transport can recreate the body for redirects/retries: `req.GetBody = func() (io.ReadCloser, error) { return io.NopCloser(bytes.NewReader(buf)), nil }`
|
||||||
|
- To duplicate a stream while reading, use `io.TeeReader` (copy to a buffer while passing through) or write to multiple sinks with `io.MultiWriter`
|
||||||
|
- Reusing buffered readers: call `(*bufio.Reader).Reset(r)` to attach to a new underlying reader; do not expect it to “rewind” unless the source supports seeking
|
||||||
|
- For large payloads, avoid unbounded buffering; consider streaming, `io.LimitReader`, or on-disk temporary storage to control memory
|
||||||
|
|
||||||
|
- Use `io.Pipe` to stream without buffering the whole payload:
|
||||||
|
- Write to `*io.PipeWriter` in a separate goroutine while the reader consumes
|
||||||
|
- Always close the writer; use `CloseWithError(err)` on failures
|
||||||
|
- `io.Pipe` is for streaming, not rewinding or making readers reusable
|
||||||
|
|
||||||
|
- **Warning:** When using `io.Pipe` (especially with multipart writers), all writes must be performed in strict, sequential order. Do not write concurrently or out of order—multipart boundaries and chunk order must be preserved. Out-of-order or parallel writes can corrupt the stream and result in errors.
|
||||||
|
|
||||||
|
- Streaming multipart/form-data with `io.Pipe`:
|
||||||
|
- `pr, pw := io.Pipe()`; `mw := multipart.NewWriter(pw)`; use `pr` as the HTTP request body
|
||||||
|
- Set `Content-Type` to `mw.FormDataContentType()`
|
||||||
|
- In a goroutine: write all parts to `mw` in the correct order; on error `pw.CloseWithError(err)`; on success `mw.Close()` then `pw.Close()`
|
||||||
|
- Do not store request/in-flight form state on a long-lived client; build per call
|
||||||
|
- Streamed bodies are not rewindable; for retries/redirects, buffer small payloads or provide `GetBody`
|
||||||
|
|
||||||
### Profiling
|
### Profiling
|
||||||
|
|
||||||
- Use built-in profiling tools (`pprof`)
|
- Use built-in profiling tools (`pprof`)
|
||||||
@ -214,7 +291,7 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Name tests descriptively using `Test_functionName_scenario`
|
- Name tests descriptively using `Test_functionName_scenario`
|
||||||
- Use subtests with `t.Run` for better organization
|
- Use subtests with `t.Run` for better organization
|
||||||
- Test both success and error cases
|
- Test both success and error cases
|
||||||
- Use `testify` or similar libraries sparingly
|
- Consider using `testify` or similar libraries when they add value, but don't over-complicate simple tests
|
||||||
|
|
||||||
### Test Helpers
|
### Test Helpers
|
||||||
|
|
||||||
@ -238,18 +315,21 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Use standard library crypto packages
|
- Use standard library crypto packages
|
||||||
- Don't implement your own cryptography
|
- Don't implement your own cryptography
|
||||||
- Use crypto/rand for random number generation
|
- Use crypto/rand for random number generation
|
||||||
- Store passwords using bcrypt or similar
|
- Store passwords using bcrypt, scrypt, or argon2 (consider golang.org/x/crypto for additional options)
|
||||||
- Use TLS for network communication
|
- Use TLS for network communication
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
### Code Documentation
|
### Code Documentation
|
||||||
|
|
||||||
- Document all exported symbols
|
- Prioritize self-documenting code through clear naming and structure
|
||||||
|
- Document all exported symbols with clear, concise explanations
|
||||||
- Start documentation with the symbol name
|
- Start documentation with the symbol name
|
||||||
|
- Write documentation in English by default
|
||||||
- Use examples in documentation when helpful
|
- Use examples in documentation when helpful
|
||||||
- Keep documentation close to code
|
- Keep documentation close to code
|
||||||
- Update documentation when code changes
|
- Update documentation when code changes
|
||||||
|
- Avoid emoji in documentation and comments
|
||||||
|
|
||||||
### README and Documentation Files
|
### README and Documentation Files
|
||||||
|
|
||||||
@ -265,7 +345,7 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
|
|
||||||
- `go fmt`: Format code
|
- `go fmt`: Format code
|
||||||
- `go vet`: Find suspicious constructs
|
- `go vet`: Find suspicious constructs
|
||||||
- `golint` or `golangci-lint`: Additional linting
|
- `golangci-lint`: Additional linting (golint is deprecated)
|
||||||
- `go test`: Run tests
|
- `go test`: Run tests
|
||||||
- `go mod`: Manage dependencies
|
- `go mod`: Manage dependencies
|
||||||
- `go generate`: Code generation
|
- `go generate`: Code generation
|
||||||
@ -288,5 +368,6 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
|
|||||||
- Not understanding nil interfaces vs nil pointers
|
- Not understanding nil interfaces vs nil pointers
|
||||||
- Forgetting to close resources (files, connections)
|
- Forgetting to close resources (files, connections)
|
||||||
- Using global variables unnecessarily
|
- Using global variables unnecessarily
|
||||||
- Over-using empty interfaces (`interface{}`)
|
- Over-using unconstrained types (e.g., `any`); prefer specific types or generic type parameters with constraints. If an unconstrained type is required, use `any` rather than `interface{}`
|
||||||
- Not considering the zero value of types
|
- Not considering the zero value of types
|
||||||
|
- **Creating duplicate `package` declarations** - this is a compile error; always check existing files before adding package declarations
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user