Coding Standards and Conventions

Naming conventions for variables, functions, and files.

Exact naming conventions vary from project to project but should always be consistent and follow best practice for the programming language. For CSS, this is usually kabab case, for JS this is camel case, or title case for JSX components. File names should generally be lowercase and avoid spaces.

Indentation and formatting

While indentation best practices vary from language to language, we recommend using spaces instead of tabs and setting indentation at two spaces, expect for languages that require tabs. Include one blank line between each logical chunk. The exact definition of a logical chunk differs between language and code content. Each file should have a trailing new line when possible.

Code Style

Always prioritize readability and maintainability over terseness. Avoid being overly verbose, but make variable and function names easy to understand.

Comments

Use comments to document any code that is not easily understood by reading it.

Horizontal rules are made up of “=” characters instead of “-” this is because many programs will swap the hyphen glyph for an em-dash, which is not the same character in plain text. Using equal signs helps prevent this accidental mutation when copying and pasting between different software.

Keep comments at most 70 characters long. This number is fairly safe when cross posting code between websites and different editor sizes.

HTML Guidelines

Prioritize HTML5 semantic tags wherever possible and make sure you’re using the correct tags for the appropriate content. Always use closing tags, even for tags that do not require them. Use role and aria attributes where necessary to improve accessibility in complex apps.

CSS / SCSS Guidelines

Use a modular methodology for CSS classes. In the institutional web framework, class names are structured like thisnamespace_component-name_child--modifier. All custom CSS should prioritize using variables from the Minerva web framework. If your project uses SCSS, it is encouraged to use Minerva's mixins and functions as well. Use global styles from the minerva framework and avoid writing or overriding global styles. Scope your CSS to an individual component or context.

Javascript Guidelines

Write clean, modular JavaScript code. Avoid over abstraction, but abstract functions any time it makes sense to do so. Always do your best to write performant javascript. Avoid large re-renders and excessive DOM manipulation.