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