Standards/Standards.md

Yzena Common Coding Standards

This document lays out common coding standards for all languages in Yzena projects.

Standards

Git

All projects must include the .gitconfig file in this repo and have a note in the README telling new users to run the following command after cloning the repo:

git config --local include.path ../.gitconfig

Submodules

Any repo with git submodules must have a note in the README telling new users to run the following command after cloning the repo:

git submodule update --init --recursive

Docs

All documentation that is not extracted from source code should be in Markdown. They must not use the equals (=) header 1 format or the dash (-) header 2 format.

There are two types of docs: those that are meant to be read directly, and those that are meant to be passed through Doxygen.

Non-Doxygen Docs

Non-Doxygen docs are meant to be readable using GitHub's web interface. They include README.md's, NOTICE.md files, and LICENSE.md files.

The title of the document must be a header 1, and every section must be header 2. Subsections must be header 3 or lower.

Any GitHub-compatible formatting can be used.

Every non-Doxygen doc must be named with all uppercase letters (excluding the file extension), using underscores (_) to separate words.

README.md Files

Every folder in an Yzena project repo should have a README.md file. It will contain a general description of the files in the folder, as well as a list of all of the files and subdirectories and their purposes.

This is so that users and developers can browse Yzena projects using the GitHub web interface and not have to guess what each directory and file is for.

Doxygen Docs

Doxygen are meant to be processed with Doxygen and put into the auto-generated documentation for the repository.

All Doxygen docs must have a title as header 1, without a header ID attribute. After the title, there must be a table of contents marker ([TOC]). There must not be any material besides the table of contents marker after the title and before the first section.

Sections must all be header 1, and subsections must be header 2 or lower. All sections and subsections must have a header ID attribute that looks like this:

{#<doc>-<section>(-<sub_section>)*}

where <doc> is the name of the document (or name of the project in the case of the Doxygen @mainpage) in all lowercase and using underscores (_) to separate words, <section> is the name of the section in all lowercase and using underscores to separate words, and <sub_section> is the name of the subsection(s) (if any) in all lowercase using underscores to separate words.

This is so a table of contents can be automatically generated. Also, the document is used as a prefix to prevent name collisions between sections in different documents.

Every Doxygen doc must be named with all lowercase letters, using underscores (_) to separate words.

Abstract

All Doxygen docs must have an abstract that list the purpose of the document. For the Doxygen @mainpage, the abstract must contain the description of the project itself.

@mainpage

Every repo must have a Doxygen @mainpage in the docs folder, usually named main.md.