Yzena Common Coding Standards
This document lays out common coding standards for all languages in Yzena projects.
All projects must include the
.gitconfig file in this repo and have a note in
README telling new users to run the following command after cloning the
git config --local include.path ../.gitconfig
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
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
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 are meant to be readable using GitHub's web interface. They
NOTICE.md files, and
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.
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 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> is the name of the document (or name of the project in the case of
@mainpage) in all lowercase and using underscores (
<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.
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
Every repo must have a Doxygen
@mainpage in the docs folder, usually named