-
Notifications
You must be signed in to change notification settings - Fork 5.8k
General Code Example Standards
Rachel Hagerman edited this page Jul 26, 2024
·
17 revisions
- Code examples should prioritize educational value and readability:
- Examples should not include code that only duplicates an API reference without additional information or context.
- Function and variable names must be clear and free of typos, with consistent capitalization and naming patterns.
- Complex logic should include descriptive comments.
- Examples must not include unreacheable code, code that does not compile or run, or code that is commented out.
- Prefer to create files as part of the examples to limit including multiple "[example].txt" files throughout the repository.
- When constructing SQL queries, use parameterized values instead of directly concatenating commands with user input.
- Console setup should not be required in order for the example to run. Any setup should happen as part of a CFN or CDK template or script, or in the program itself. The only exception is for "feature access", such as enabling access to a Bedrock model.
- Provide customers with appropriate context in published documentation through metadata and snippet organization.
- Describe the program flow and instructions for readability, file creation, and CFN or CDK resource deployment.
- Code comments must be descriptive, use complete sentences (with punctuation), and be free of typos or grammatical errors.
- Language owners may establish their own patterns for comments (such as parameter and method descriptions) and should follow those patterns consistently.
- Describe any important comments that should be included in all implementations.
- When pagination is available (determined by checking the service client for paginators), the available paginator must be used.
- In cases where a subset of items is intentionally fetched, it should be noted in the code comments.
- If the intent is listing "all" items, pagination should be included to return all pages of data.
- Hello Service examples should still demonstrate pagination if available, but can log the total count of items (along with a subset of the list, if desired) instead of listing all items.
- Indicate where pagination is required.
- When a waiter is available, it should be used in the example.
- If no waiter is available, the program should poll for the applicable status before continuing.
- If a sleep() function is used, a descriptive comment must be included explaining why.
- Indicate where a waiter is required.
- Each discrete service call with specific exceptions (such as "resource not found" or "resource already exists") should demonstrate capturing at least one possible exception and handling it appropriately.
- Examples should not break/quit for their exception handling unless there is a reason to do so, so that resources can be cleaned up gracefully.
- Indicate which specific exception should be handled, and what should happen when that exception is caught.
- Resource ARNs or names should either be entered by the user, provided as program arguments, or loaded from a separate configuration.
- Code should not use hard-coded strings or "<REPLACE_THIS_STRING>" placeholders to access necessary resources.
- Examples should not use hard-coded Regions unless necessary for the example.
- Specify how program arguments should be loaded.
- User names and passwords or other security artifacts should be entered by the user and not referenced as hard-coded strings.
- They should not be stored or retained, and only pass through to the necessary service, in cases such as Cognito user setup or RDS admin setup actions which require a password.
- Describe any special handling for security items.
- New code should have test coverage (can be unit or integration) for each method or logical operation block.
- Refer to the SDK language specification page for test tool details.
- Follow general guidance for testing, no additional specification requirements.
- If any user configuration, program Args, or other setup is required, they should be described in the code comments and/or the README for that service or services(s).
- Include descriptions for configurations if they are language-agnostic.
- Resources created as part of an example should be cleaned up as part of the program.
- This can include a y/n question to the user before deleting resources.
- If a scenario does not complete due to errors, it should attempt to run the cleanup operation before exiting.
- Include a description if anything other than a y/n question is needed.
- Examples should follow the repository standards for adding and managing digital assets and sample files.
- Include instructions for retrieving/using any shared digital assets. Prefer shared assets over duplication in each language folder.
- Should demonstrate a single service action to get customers started using an SDK with a service.
- Should be copy-paste runnable to reduce any blocks for the user, ideally in a main function or similar.
- Include imports, service client creation, etc.
- Make a single service call to something that requires no input (ListBuckets, etc.). If Hello Service exists for other languages, use the same Action so they are all consistent.
- If pagination is appropriate/available, use it. You may also limit the number of results.
- Print something useful about the output, don't just dump the output (bucket names, etc.).
- Error handling is optional and only if it makes sense.
- The first implementation for an example (Basic or Workflow) must also include the Hello Service as part of the specification.
| Language | Package | Version | Formatter | Linter | Checker | Unit | Integration | Language Guide | Language Guide Notes |
|---|---|---|---|---|---|---|---|---|---|
| CLI | shellcheck | Weathertop | Shellcheck linter | ||||||
| C++ | git | main | Weathertop | C++ Coding Standards Guide. | SDK coding standards for C++. | ||||
| .NET | nuget | SDK V3 (.NET 6 or later) | dotnet format | dotnet format | dotnet build | XUnit | Weathertop | C# (.NET) Code Conventions. | Recommended C# coding conventions for .NET, referenced by the .NET SDK team and used for formatting checks by dotnet format. Based on the same .editorconfig for dotnet format. |
| Go | Go Mod | go-v2 v1.15.3 | gofmt | golangci-lint |
go build | testing (builtin) | Weathertop | Amazon GO Wiki: | Amazon’s GO resources and structure guidelines. |
| Java | Maven | 2 | checkstyle | checkstyle | JUnit | Weathertop | Oracle Java Code Conventions. | Reflects the Java language coding standards presented in the ** Java Language Specification, from Sun Microsystems, Inc. | |
| JavaScript | NPM | ^3.210.0 | prettier | eslint | typescript | vitest | Weathertop | [AirBnB base guide](http:// https://github.com/airbnb/javascript) | |
| Kotlin | gradle | 0.30.1-beta | ktfmt | ktlint | kotlin | Weathertop | Kotlin Coding Conventions. | Coding and style conventions by the Kotlin team. | |
| PHP | composer | 3.283.2 | phpcs (PSR-12) | phpcs | php | phpunit | Weathertop | PSR-12 Basic Coding Standard for PHP | Extended coding style guidelines for PHP. |
| Python | Pip | boto3 >=1.26.79 | Black | pylint | mypy | pytest | Weathertop | PEP 8 - Style Guide for Python Code. | Coding conventions for the Python code comprising the standard library in the main Python distribution, used as reference only. |
| Ruby | gem | Weathertop | Ruby Style Guide. | Recommended best practices for the Ruby language. | |||||
| Rust | Cargo | next | cargo fmt | cargo clippy | cargo check | cargo test | Weathertop | Rust Style Guide. | Defines the default Rust style and formatter recommendations, by the Rust team. |
| Swift | 0.28.0 | Weathertop | Swift Style Guide. | Google’s style guide for Swift, based upon Apple’s Swift standard library style. |