For any sufficiently big feature, we want to make sure that:

• we agree on the design before we implement it, and
• we have some documentation for it after it’s finished.

Specs and design docs

If the feature you are working on doesn’t have a trivial and universally expected implementation, it is a good idea to start by writing a spec or design doc.

It would be sufficient to create a new document in Master Docs, fill in all the required fields, and add the following:

• Problem statement.
• Overview of possible solutions.
• A more detailed description of the proposed solution with rationale.

Once completed, broadcast the doc to relevant people to gather feedback. If there are no major concerns, you can proceed with the implementation.

Whenever possible, you should also try to keep the doc up to date with implementation, as later it can be used to understand the principles under which the feature was implemented.

Code comments

Good documentation is close to the code. It is easier to keep code comments up to date than any documentation that exists elsewhere, and code comments are much more likely to be read.

It is advised to ship the code with comments showing:

• Purpose: what’s the problem being solved here?
• Invariants: what are the assumptions for the inputs?
• Maintenance notes: what changes are desired? What changes are not desired?
• Any information that is otherwise useful for developers. Avoid, however, simply repeating what's written in the code. If the code has readability issues, it's better to consider refactoring.

Even though it is often stated that good code should be self-documenting, the code alone cannot provide you with the context in which this code has been written. This context often explains the reasoning behind certain design decisions and the limitations of the solution. Thus, by providing elaborate comments, you help other developers (including your future self) to interact with the code in an intended way.

Whenever possible, you should use the functionality provided by your language or its tooling to generate documentation from comments (e.g. rustdoc or TSDoc). As part of developing in the open we’re starting to host more and more documentation for our code, so the ability to automatically generate code documentation is extremely valuable.