1
0
mirror of https://codeberg.org/emilwilliams/chad_standard synced 2024-11-25 20:48:38 -05:00
chad_standard/chad.tex

259 lines
8.2 KiB
TeX
Raw Normal View History

2024-07-20 02:14:16 -04:00
\documentclass{article}
\newcommand{\bitem}[1]{
\item \textbf{#1}
}
\renewcommand{\familydefault}{\sfdefault}
% \setlength{\oddsidemargin}{20pt}
% \setlength{\textwidth}{400pt}
\title{\textbf{Chad Standard}}
\date{Draft 1, 2024, July 18th}
\begin{document}
\maketitle
\Large\section{Preface}
A standard is meant to define a set of rules and guidelines, simply put, this document does that in a shorthand fashion. For any self-respecting project, the rulings here should lead to a decently readable codebase with a strong consistency. Above the standard there is only one rule: the Rule Of Consistency, prefer being self-consistence to any strict compliance.
\paragraph{Authors}
Written by \textit{Emil Williams}, and was designed by an Anonymous contributor and \textit{Ognjen M. Robovic}. The authors of this text democratically came to these outcomes over rational discussion with full agreement on each point.
\paragraph{This Document}
Being designed with only the C Programming Language in mind. Rulings should not apply to other languages. This document was invented by the means of \LaTeX \\ and by no other means could it possibly have been made.
\pagebreak
\small\section{Standard}
\begin{enumerate}
\bitem{Line Width}
72 or higher (ex. 80, 120, 240, etc.)
\bitem{NULL Terminator In String Literal}
Always use: $\backslash00 \rightarrow \backslash0$
\bitem{Hexadecimal Literals In String Literal}
2 digit hexadecimal values: $\backslash$$xDE\backslash$$xAD$
\bitem{String Literal NULL Terminator Breaks} \\
"text$\backslash0$" "more text$\backslash0$"
NULLs should be grouped:
"$\backslash0\backslash0$"
Given that your creating an explicit String Literal containing many
cstrings, individual NULLs may be given their own group.
% \bitem{Once Explicit, Always Explicit}
\bitem{C99 Leading Commas}
In enums or compound literals, leave a leading comma.
If you're writing for C89, then you should never use Leading Commas.
\bitem{Do Not Use $union$ or $struct$ In Declarations}
A $union$ or $struct$ may be stated such that variable $a$ of struct
type $b$ would be declared as $struct$ $b$ $a$ rather than $b$ $a$.
\bitem{C99 Compound Literals}
If you explicitly set some item in the structure or union, you
must do this for all other items in the structure.
\begin{verbatim}
typedef struct {
int a, b;
} type;
type a = {
.a = 1,
.b = 2,
};
\end{verbatim}
% \bitem{Compilation}
% Provide a Makefile.
\bitem{No Relative Header Paths}
Do not use relative pathing in headers, instead use compiler flags
or full paths to enable your compilation.
2024-07-20 13:17:05 -04:00
\bitem{Define At Beginning Header Guard} \\
2024-07-20 02:14:16 -04:00
Use this kind of header guard:
\begin{verbatim}
#if HEADER_H
#define HEADER_H
2024-07-20 13:17:05 -04:00
...
#endif // HEADER_H
2024-07-20 02:14:16 -04:00
\end{verbatim}
2024-07-20 13:17:05 -04:00
\bitem{No Double Blank Line} Shortens code and removes blank redundancy, use Single Blank Lines as much you want.
2024-07-20 02:14:16 -04:00
\bitem{Namespacing For Externally Exposed Headers \& Variables}
Add a namespace suffix for headers \& variables meant to be used
outside your project.
\bitem{Acceptable Naming}
Names should be of one format and only one format internally.
The endorsed naming style is\_snake\_case, snake\_case\_for\_all.
\bitem{Use Tabs And Spaces}
Effective use of both tabs and spaces aids in code density and
universal styling regardless of tabwidth.
\bitem{Parenthesize All Macro Definitions}
This is to insure precedent is maintained such that macros will be
computed to one value.
\bitem{Include Padding After Commas}
Do, This, In a list, so you can, separate things better,
visually. rather,than,this,pile,of,nonsense.
\bitem{$extern$ All Function Declarations}
Visually signifies your declarations.
\begin{verbatim}
extern int func (int a, int b);
\end{verbatim}
\bitem{Padding For All}
Functions, Declarations, and Math should all have padding after
their respective incantation, and before if and when applicable.
\begin{verbatim}
int func (int a, int b) {
int c = a * b + 1;
return a + b + c;
}
func (2, 5);
\end{verbatim}
\bitem{Center Pointer Declaration}
\begin{verbatim}
void * pointer;
\end{verbatim}
even for typecasting
\begin{verbatim}
(int *) malloc (sizeof (int));
\end{verbatim}
\bitem{Sparse Pointers Types}
\begin{verbatim}
void * * double_pointer;
void * * * triple_pointer;
void * single_pointer;
\end{verbatim}
\bitem{Always Specify $malloc$ This Way}
\begin{verbatim}
type a variable = (type a) malloc (sizeof (type b) * number of items);
\end{verbatim}
\bitem{Single Line Parameters}
Function parameters should remain on the same line. If a function has
way too many parameters (line length greater than limit), format them
into a block such that they are placed after the initial open
parentheses.
\bitem{Alignment Of Variable Names}
Align adjacent declarations horizontally.
\bitem{Alignment Of Assignments}
Align adjacent assignments horizontally.
\bitem{always $typedef$ $enum$, $struct$, and $union$ constructs}
\bitem{Anonymous Structures}
You may use these if you wish to.
\bitem{Always Bracket} With the only exception being $else$ $if$. This includes switch statement case bodies.
\bitem{Full body $switch$ Format} Bodies may be either Multi-line or single line, but the body must be put inside braces.
\begin{verbatim}
switch (...) {
case ...: {
break;
}
}
\end{verbatim}
Cases do not need to have break statements, and do not have any restriction or suggestion on control flow.
\bitem{Left Handed $if$ Format}
\begin{verbatim}
if (!a
&& b) {
...
}
\end{verbatim}
\bitem{Reduce $if$ Format}
Avoid Pointless Comparisons
\begin{verbatim}
if (a)
\end{verbatim}
instead of:
\begin{verbatim}
if (a != 0)
\end{verbatim}
\bitem{Preferred Iterators $i$, $j$, $k$, $...$}
\bitem{Preferred Iterator $while (1)$} Decide on whether you should obey this based on your compiler, if this is not equivalent to $for (;;)$ then use that instead.
\bitem{Prefer Prefix Decrement $-$$-$$x$ Increment $++x$} If you must use the de/increment operator, then use Prefix Increment unless you can justify use of Suffix Increment.
\bitem{Use Preprocessor Comments To Comment Out Code} \\
They're actually recursive:
\bitem{C99 Style Declarations For Loop Iterators} Including the declaration is acceptable if there's no other use of the iterator, otherwise the declaration should be in the scope above.
\bitem{Parentheses For Absolutely Everything}
\begin{verbatim}
return (1);
\end{verbatim}
\begin{verbatim}
#if 0
...
#endif // 0
\end{verbatim}
\end{enumerate}
\pagebreak
\large\section{Project Advice}
These are just some suggestions that are per-project and are not to be followed word to word. Pick your poison and deception.
\begin{enumerate}
\bitem{Provide Makefile} It's generally universal in the Unix world.
\bitem{Provide @BAKE compilation header} For small projects $:$$)$ https://github.com/emilwilliams/bake
\bitem{Cure, Sanitize, Analyze} \\
Make sure to clear compiler warnings, such as those generated by $gcc$(1) and $clang$(1) under $-Wall$ $-Wextra$ $-Wpedantic$; runtime issues found by sanitation tools such as $-fsanitize=address,undefined,bounds$ or $valgrind$(1); and static analysis tool such as $split$(1)
If you fail to preform these acts, the man of two dashes will be displeased, and you will lose 88\% of your maximum health for 2d144 turns.
\bitem{You Don't Need More Than A Triple Pointer} It's rather excessive.
\bitem{You Don't Need More Than Three Iterators} It's rather excessive, unless your implementing an algorithm or larger system that needs it, even then it may be more reasonable to isolate these systems and then $static$ $inline$ them.
\bitem{You Don't Need More Than $4$ Levels Of Indentation} You should put that inside a function!
\bitem{Don't You Dare Use C Style Comments, Emil!} C Style Comments are not justified unless you absolutely need them,
C++ Style Comments in all normal cases are useful for logical separation and denser comments.
C Style Comments are for larger explanations, NOT for commenting out blocks of code!
\bitem{Use C Style Comments Always And Vanquish C++ Demons From Your Code, Anon!} Given that you hate C++ (obviously), you can vanish them by using C Style Comments always because you don't know how to make Emacs not do that by default, and you don't feel like fixing it or learning to type $//$.
\bitem{Use POSIX Reserved $\_t$ Suffix For New Types}
\end{enumerate}
\end{document}