Guides

Guides for working together, getting things done, programming well, and programming in style.

High level guidelines

• Be consistent.
• Don't rewrite existing code to follow this guide.
• Don't violate a guideline without a good reason.
• A reason is good when you can convince a teammate.

A note on the language

• "Avoid" means don't do it unless you have good reason.
• "Don't" means there's never a good reason.
• "Prefer" indicates a better option and its alternative to watch out for.
• "Use" is a positive instruction.

Guides by category

• thoughtbot Tech Stack
• General

Collaboration

• Code Review
• Open Source
• Product Review

Protocols

• Accessibility
• Data
• Email
• Object-Oriented Design
• Security
• Web
• Web Performance
• Production

Languages

• Bash
• CSS
• ERB
• HTML
• JavaScript & TypeScript
• Python
• Ruby
• Sass
• Shell
• Swift

Frameworks and platforms

• Android
• iOS
• Rails
• React
• React Native
• Testing with Jest
• Testing with RSpec

Tools

• Git
• GraphQL
• Postgres
• Relational Databases

Contributing

Please read the contribution guidelines before submitting a pull request.

In particular: if you have commit access, please don't merge changes without waiting a week for everybody to leave feedback.

Credits

Thank you, contributors!

License

Guides is © 2020-2025 thoughtbot, inc. It is distributed under the Creative Commons Attribution License.

About thoughtbot

This repo is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software! See our other projects. We are available for hire.