Style guides

API soft-delete query string design pattern.md

API model query string

• is_archived=*: Returns a list of both soft-deleted and non-soft-deleted records
• is_archived=true: Returns a list of only soft-deleted records
• is_archived=false: Returns a list of only non-soft-deleted records
• absent is_archived: Returns a list of only non-soft-deleted records

Example

GET http://www.example.com/api/1/models?is_archived=*

Database column

• datetime deleted_at or
• datetime archived_at

API style guide.md

Use JSON API when possible

Rationale

Using a well-defined, consistant standard helps make your implementation more consistant and easier to adopt, especially in less-flexible systems where variations are difficult to implement or where there is a pre-built library that implements the standard.

Use JSON

Rationale

Using a well-defined, consistant standard helps make your implementation more consistant and easier to adopt, especially in less-flexible systems where variations are difficult to implement or where there is a pre-built library that implements the standard.

Use consistant headers

Rationale

Using consistant headers such as content-type: application/json helps make your implementation more consistant and easier to adopt, especially in less-flexible systems where variations are difficult to implement or where there is a pre-built library that implements the standard.

Always include successful boolean at the root level

Rationale

Including a consistant predictable boolean value at the root level makes it easy for implementers of the API to identify if the API was successful or failed.

Example

{
  "successful": true
}

On error, use errors array

Rationale

Using a consistant errors array that contains a list of errors, even when there is only one error makes it easier for implementors to display error messages to the user or process errors.

Example

{
  "errors": [
    {
      "message": "Username is required",
      "data": {
        "Field
      },
    },
  ],
  "successful": false
}

Todo

• Document your API

database migrations style guide.md

Start migration names that create tables with create

Rationale

Using a consistant and clear standard helps make quickly scanning the migration list easier and is helpful when manually scanning for specific migrations.

Use rollbacks when available

Rollback migrations are migrations that undo the changes from another migration. For example, when a migration creates a new table, the rollback would drop the table.

Exceptions

Sometimes creating a rollback is difficult or requires more data than is available. For example, if a migration copies data from one table to another to move the data to a new table and retire the old one, the rollback migration will not know what records were copied and what data was later inserted. In these cases, it may make sense to have an empty rollback.

Todo

• Naming convention for creating new tables
• Naming convention for adding a column to a table
• Naming convention for renaming a column
• Naming convention for

HTML-CSS style guide.md

Avoid !important whenever possible

Rationale

Using !important in a style maks it very difficult to later override that style if needed, and can mangle the styles on other parts of the website if the selector is too broad.

Exceptions

It is sometimes acceptible to use !important when other styles on the page make it impossible to use other approaches and if and only if a very specific css selector is used, such as a non-container element selector inside a unique css class container, or rarely used and uniquely named css class.

Do not add styles to framework CSS classes

Rationale

Styles applied to native classes will make it much more difficult to add elements that use the framework styles.

Example

Include bootsrap, that has a btn class. Apply custom styles to make a rounded button.

.btn {
  border-radius: 20px;
  border: none;
  text-transform: uppercase;
}

Alternative

.rounded-button {
  border-radius: 20px;
  border: none;
  text-transform: uppercase;
}

Style guide style guide.md

Include a rationale

Rationale

The rationale for a style helps educate the reader to the reasons for the style. In addition, a rationale helps the reader know if a style is outdated and no longer applies, or if it does not apply to their situation.

Example

Many years ago the standard for code width was 80 characters. This standard may date back to punchcards and later terminal width, but is contested today due to the fact that most screens have much higher resolutions and can fit more characters. A rationale on a 80 character width style would help a reader understand if the style applies to them and lets them decide if they wish to adopt or abandon the style.

Todo

• Include examples and alternatives
• Include exceptions