-
Notifications
You must be signed in to change notification settings - Fork 5.7k
Code comment guidelines
Liz Kellebrew-Davies edited this page Mar 10, 2022
·
3 revisions
With any given piece of code, the most likely person to look at it next and struggle to understand it will be the developer.
Each code file should tell a story so that the developer understands what each part of the code does. All other information, such as prerequisites and instructions for running the code, should be in the associated READMEs.
Excessive code comments can make the code more difficult to follow. To mitigate this, try to write code that is as human-readable and self-explanatory as possible. However, don’t try to be too clever. If what your code is doing isn't obvious, include descriptive comments about non-obvious reasons for doing things.
Here are some examples:
- Ruby code example - Code that is human-readable and includes functional comments
- Go code example - Code that tells what it's doing (not so much how __it's doing it), but is written in a human-readable fashion
- Rust code example - Very human-readable code
- About the AWS SDK Code Examples repo
- Code quality guidelines - testing and linting
- Code comment guidelines
- Sample files guidelines
- Cross-service example guidelines
- README templates
-
Code example standards
- General standards
- .NET code example standards
- C++ code example standards
- CLI/Bash code example standards
- Go code example standards
- Kotlin code example standards
- Java code example standards
- JavaScript code example standards
- PHP code example standards
- Python code example standards
- Swift code example standards
- SAP-ABAP code example standards
- Ruby code example standards
- Rust code example standards