-
Notifications
You must be signed in to change notification settings - Fork 19
Style Guide
This document describes a few principles of style for work related to the V&T Task Force.
The primary goal of these style guidelines is to improve code readability so that everyone, whether reading the code for the first time or maintaining it for the future, can quickly determine what the code does. Secondary goals are to design systems that are simple, to increase the likelihood of catching bugs quickly, and avoiding arguments when there are disagreements over subjective matters.
Write what you need and no more, but when you write it, do it right.
Avoid implementing features you don’t need. You can’t design a feature without knowing what the constraints are. Implementing features "for completeness" results in unused code that is expensive to maintain, learn about, document, test, etc.
When you do implement a feature, implement it the right way. Avoid workarounds. Workarounds merely kick the problem further down the road, but at a higher cost: someone will have to relearn the problem, figure out the workaround and how to dismantle it (and all the places that now use it), and implement the feature. It’s much better to take longer to fix a problem properly, than to be the one who fixes everything quickly but in a way that will require cleaning up later.
You may hear team members say "embrace the yak shave!". This is an encouragement to take on the larger effort necessary to perform a proper fix for a problem rather than just applying a band-aid.
When you fix a bug, first write a test that fails, then fix the bug and verify the test passes.
When you implement a new feature, write tests for it.
If something isn’t tested, it is very likely to regress or to get "optimized away". If you want your code to remain in the codebase, you should make sure to test it.
Don’t submit code with the promise to "write tests later". Just take the time to write the tests properly and completely in the first place.
We will be adhering to PEP-8 standards as closely as possible. These are widely accepted standards for how good, clean code should look. Let's keep things tidy!