# 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. 

![](/files/-LCd1jBQB35CWcErTrTL)*Example of a well documented controller*

![](/files/-LCd1jCAfqY2XA6_TjZF)*Example of an RSpec testing a controller, using the Swagger helpers that define swagger documentation*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://omalab.gitbook.io/engineeringwiki/working/best-practices/code-documentation-using-yard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.