Code Documentation (using Yard)

Code documentation is a CRITICAL aspect of writing professional grade code. In all cases, we must strive for code that is simple, clean, organized, consistent, DRY, and tested.

To accomplish this, there are a few standards we are employing to make this happen:

In Code

• We use YARD to document our code when we are writing the code. This means that the class should have a description on the top of it that defines what the class does. What is its goal, and how is this class used. In addition, each method should have a description for what this code does as well. At a minimum, unless the method does NOTHING (which it should be removed) at least a 1 line description should be there, plus a definition of what a return should look like.

• We use Swagger, automatically generated from our RSPEC tests, for documenting our API. If you are working on the API, you MUST define your API controller's behavior using the swagger helpers. These provide get/post and response code handling that lets us create swagger documentation for the API.

Example of a well documented controller

Example of an RSpec testing a controller, using the Swagger helpers that define swagger documentation