- Follows appropriate style guide for the language
- When possible match the style of the file you are working in
- When possible utilize the language specific linting scripts to automatically detect style issues (which should also be part of the smithy build process)
- Golang - gofmt
- Dart - Over React Format - example from wdesk_sdk
- Write self documenting code
- Create descriptive variable and function names
- Add comments when what you are doing isn’t completely obvious
- Functions should do one thing
- TODOs or FUTURE comments in code should be cleaned up before code is merged or accompanied by a JIRA ticket for follow up work
- Commented out code should not be merged
- Include docstrings on all exported symbols.
- Keep the console and logs clean - (i.e. remove unneeded print/debug statements and ensure no RTEs occur on client or server side)
- Avoid the use of Magic Strings
- APIs should include documentation
- Use the documentation portal to document the API (i.e. add a docs.yml to the repo)
- docs.yml examples from wTranslate and wCRDT
- Dart
- Refer to Effective Dart
- Memory management best practices should be followed
- Test ids have consistent names and added as we add functional tests
- Go
- Read the Workiva Go Best Practices
- Refer to Effective Go and Go Proverbs):
- A little copying is better than a little dependency.
- Code to interfaces! Having to stand up networked resources for unit tests is not fun.
- Unit testing is hard, write as functionally as possible to ease injectability.
- Turn on gofmt in your IDE.
- Bash
- Use GNUMake to do your work in a cross platform fashion.
- Write good commit messages.
- Include the what and most importantly the why
- Include the ticket number
- Optional - setup a git commit-msg hook that does this for you - example
- Optional - verify your commits (added security) - article
- Consider adding tracing spans to a function in the following scenarios:
- RPCs (e.g. thrift and frugal)
- Sending data to persistence or other services (e.g. S3, RDS, SQS)
- Potentially expensive operations (lots of complexity) - use your judgement
Many developers use VSCode for daily development with the following extensions:
- Spell Checker
- Go-lang Plugin
- Highlighting for Thrift and Frugal files
- Better icons library
- Golang TDD
- JSON Tools
- Plant UML
- Git Lens — git blame annotations, code lens, and more
- Git History
- Find Go Interface Implementations
A suggested settings file is located at .vscode/init_settings.json and can be enabled by renaming the file to settings.json.
Other editors are acceptable as well including:
- IntelliJ
- vim
- atom
If you have plugins / tips for these or other editors feel free to add content above
If you have any other books/articles please add them to this list! (i.e. create a PR to this file)