- Two spaces to indent. Be anal about this.
- Write code in English.
- Code must work.
- Code must be easy to understand.
- Critical code should be efficient.
- Use standardrb, a minimal, opinionated ruby formatter with a sane default config. Make sure everyone is using it from the beginning.
- When in doubt, try to follow the GitHub Ruby Style Guide. In general it’s pretty good.
- Avoid religious wars. They’re too bloody and everyone goes to hell in the end.
After that, let’s all just try to get along. Seriously, we all have our preferred coding styles and the existing codebase has had many hands in it over the years. The goal is to write good, clear code. After that, we are a business and the goal is to build a profitable product. Don’t waste time on things that don’t support that end.
Follow the guidelines. Don’t waste time cleaning up coding just because you think it could be prettier. Learn to love your neighbor’s code otherwise he’ll just up and rewrite your code when you aren’t looking.
- Add a comment at the top of each class file explaining what it is for. Even if you think it’s obvious. You don’t have to write a novel, usually a sentence is more than enough.
- Add a comment before a method where it isn’t patently obvious what it does or if it has some sort of side effect. You’ll find doing so pays excellent dividends when you don’t have to keep answering the same questions over and over.
- Add a comment to code when you do something that doesn’t look right. You know which code this. Often it’s an optimization or hack needed to avoid a bug. Let the world that you do indeed know what you’re doing and are not in fact a clinical idiot whose code needs to be constantly rewritten.
- Use protected and private methods for methods that don’t need to be called by other classes. Otherwise you’ll need to write tests for them and who wants to do that? Keep the public API of your classes small.
- Logically group like classes inside modules. Especially in the models directory. That thing can get huge if doesn’t have an subdirectories.
- Use descriptive names for classes, methods, and variables. We all hate writing documentation and you probably aren’t going to do it anyway, so let’s make sure most things are self documenting. Of course we don’t want to be zealots about this. Using a short variable name inside a single line iterator is perfectly fine.
- Follow existing patterns in the code and accepted by the Rails community.
- Pay attention to deprecated code and don’t add more of it.
- Don’t be anal about the 80 column limit.
- Use Hash parameters when more than three arguments are needed in a method.
- When things go wrong and you fix it, make sure it doesn’t happen again. Write a test. Write a comment. Whatever it takes.
- Don’t make wholesale changes to existing code just to match a preferred style. If you need to edit a method in a large class file, don’t go and refactor the whole file just to match your coding style. Doing so just adds to the scope of your work and makes reviewing the change more challenging.
- Don’t troll all the commits and suggesting minor style changes. I’m pretty sure you have more important things to do. So does everyone else who ends up reading and then adding to the discussion.
- Don’t worry about how elegant the code looks. Not every line can be a masterpiece and sometimes you need to make compromises. It’s code. Is it clear? Does it work? Great! Move on.
- Don’t add new architecture patterns because they sound neat on a blog post. We need to keep the code base understandable and stable and adding the newest, shiniest toys doesn’t always serve this end. Major changes need to be justified to the business.
- Don’t change the style formatter just to suit your personal preferences. These tools can end up making mass changes that make reviewing changes very difficult.
- Use ‘preload’ instead of ‘includes’ on ActiveRecord relations. Rails will do the wrong thing if you let it. I promise.