contributing_comments

Comments were always a conflicting topic in any programming language, so much there are some developers believe they should be completely abolished, but we are not followers of this misbelief, we took what was considered garbage and made it a helpful tool. We divide comments into three different types (that serve different purposes):

JSDoc

Our good ol JSDOC, when working with libraries, frameworks or any other projet that you should pass information easily accessible outside of the actual script, this is the go to. Most editors can strip JSDocs from typescript, but that doesn't mean they aren't there or that you shouldn't further describe them. They can contain examples, notes and other useful mechanisms that can help people working with a specific method or class.

Descriptive

This are the comments you are most used to see, they describe business logic, explain certain quirks of a method or tell us certain part of the code needs refactor. Imagine those comments as a label of a image in a book.

// this creates a valid hex hash for the api
const token = Hash.hash(value).salt(process.env.APP_KEY).type(api.validFormats.TOKEN);

Sectional/organizational

Those comments are important for their existance more than their content. This means that they serve as a visual mark to divide portions of our code, making it easy to identify them with a rapid scrolling or through a minicode (usually present in most text editors).

// -------------------------------------------------
// Helper methods
// -------------------------------------------------

function hash (value) {}

// -------------------------------------------------
// Main methods
// -------------------------------------------------

export function index (req: HttpRequest) {}