-
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.