From 63c545d77d5ede8fc694daa936d147bcd24a9627 Mon Sep 17 00:00:00 2001 From: JozanLeClerc Date: Tue, 17 Nov 2020 00:49:04 +0100 Subject: Fix --- docs/dergods_style_v0.1.ms | 169 -------------------------------------------- docs/dergods_style_v0.1.org | 104 --------------------------- docs/dergods_style_v1.ms | 169 ++++++++++++++++++++++++++++++++++++++++++++ docs/dergods_style_v1.org | 104 +++++++++++++++++++++++++++ 4 files changed, 273 insertions(+), 273 deletions(-) delete mode 100644 docs/dergods_style_v0.1.ms delete mode 100644 docs/dergods_style_v0.1.org create mode 100644 docs/dergods_style_v1.ms create mode 100644 docs/dergods_style_v1.org diff --git a/docs/dergods_style_v0.1.ms b/docs/dergods_style_v0.1.ms deleted file mode 100644 index fff2c0a..0000000 --- a/docs/dergods_style_v0.1.ms +++ /dev/null @@ -1,169 +0,0 @@ -.defcolor blue rgb 0.1f 0.1f 1.0f -.defcolor bsdred rgb #990000 -.defcolor codered rgb #600000 -.defcolor grey rgb #aaaaaa -.defcolor black rgb #000000 -.color -.de bsdr -.gcolor bsdred -.. -.de endc -.gcolor -.. -.de xa -.XA \\$1 -.ps 12p -.B "\m[bsdred]\\$2\m[]" \\$3 \\$4 -.. -.de b -.B "\m[bsdred]\\$1\m[]" \\$2 \\$3 -.. -.de code -.gcolor bsdred -.CW \\$1 \\$2 \\$3 -.gcolor -.. -.de nh1 -.gcolor bsdred -.NH 1 -.ps 14p -\\$1 -.gcolor -.. -.de nh2 -.gcolor bsdred -.NH 2 -.ps 13p -\\$1 -.gcolor -.. -.de bu -.IP \(bu 2 -.. -. -. -. -. -.nr PS 12p -.nr PO 1.0i -.nr LL 6.5i -.RP no -.P1 -.ND -. -. -. -. -.gcolor black -.bsdr -.TL -.LG -.ps 17p -Dergods' Style and good practices for C/C++ projects -.endc -.AU -.ps 15p -Joe -.AI -42 Lyon Auvergne-Rhône-Alpes -. -. -.XS 1 -.ps 12p -.b "1. Introduction" -.xa 1 "2. Projects and version control" -.xa 1 " 2.1 Directories" -.XE -.bsdr -.PX -.endc -. -. -.nh1 "Introduction" -.PP -The following is a description of -.b "Dergods' Style" -code and project -formatting to put in use if you work on Dergods' Realm-related code or if you -just need a personal good-looking norm to improve your code readablity. It -is heavily inspired by -.b FreeBSD® 's -.pdfhref W -D \ -https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=0&\ -manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html \ --A \m[black],\m[] \ -\f(CW\m[codered]style(9)\m[]\f[] -.gcolor -with some changes. -.nh1 "Projects and version control" -.nh2 "Directories" -.RS -.bu -Working on a -.b program : -.RS -.bu -All -.b source -and -.b "header files" -should be in the -.code src/ -directory. -.bu -Necessary -.b "media files" -such as images, sounds, fonts, etc... Necessary to the program execution -should be in the -.code media/ -directory. -.bu -Compilation-generated -.b "object files" -should be located in the -.code obj/ -directory. -.bu -.b Sub-programs -or -.b utilities -should be located in the -.code utils/ -directory. -.bu -Optional -.b "man page(s)" -can be made for the project and its specularities and should be located in the -.code man/ -directory. -.RE -.bu -Working on a -.b library : -.RS -.bu -All -.b "source files" -should be located in the -.code src/ -directory. -.bu -Compilation-generated -.b "object files" -should be located in the -.code obj/ -directory. -.bu -Non-optional -.b "man pages" -for every function intended to be used externally -should be located in the -.code man/ -directory. -.bu -.b "Header files" -should be located in the -.code include/ -directory. -.RE -.RE diff --git a/docs/dergods_style_v0.1.org b/docs/dergods_style_v0.1.org deleted file mode 100644 index 7d27312..0000000 --- a/docs/dergods_style_v0.1.org +++ /dev/null @@ -1,104 +0,0 @@ -#+TITLE: Dergods' Style and good practices for C/C++ -#+AUTHOR: Joe -#+DATE: v0.1 -#+LATEX_CLASS: article -#+LATEX_CLASS_OPTIONS: [a4paper] -#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} -#+LATEX_HEADER: \usepackage[utf8]{inputenc} -#+LATEX_HEADER: \usepackage[dvipsnames]{xcolor} -#+LATEX_HEADER: \definecolor{mypink1}{rgb}{0.858, 0.188, 0.478} -#+LATEX_HEADER: \let\OldTexttt\texttt -#+LATEX_HEADER: \renewcommand{\texttt}[1]{% -#+LATEX_HEADER: \OldTexttt{% -#+LATEX_HEADER: \colorbox{gray}{% -#+LATEX_HEADER: \color{black} #1% -#+LATEX_HEADER: }% -#+LATEX_HEADER: }% -#+LATEX_HEADER: }% - -* Introduction -The following is a description of Dergods' Style code and project -formatting to put in use if you work on Dergods' Realm-related code or if you -just need a personnal good-looking norm to improve your code readablity. It -is heavily inspired by BSD [[https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html][style(9)]], -with some changes. - -* Projects and version control -** Directories - - Working on a *program*: - - All source and header files should be in the ~src/~ directory. - - Necessary media files such as images, sounds, fonts, etc... To the program execution should be in the ~media/~ directory. - - Compilation-generated object files should be located in the ~obj/~ directory. - - Sub-programs or utilities should be located in the ~tools/~ directory. - - An optional man page can be made for the program and should be located in the ~man/~ directory. - - Working on a *library*: - - All source files should be located in the ~src/~ directory. - - Compilation-generated object files should be located in the ~obj/~ directory. - - Non-optional man pages for every major function should be located in the ~man/~ directory. - - Header files should be located in the ~include/~ directory. - -** Files - - *C* sources and headers files should be of the ~.c~ and ~.h~ extensions. - - *C++* sources and header files should be of the corresponding ~.cxx~ / ~.hxx~ or ~.cc~ / ~.hh~ extensions unless the project is Microsoft™ Windows®-compatible only, then extensions should be ~.cpp~ / ~.hpp~. If the project is compatible with any UNIX®-like operating system, ~.cxx~ / ~.hxx~ or ~.cc~ / ~.hh~ should be the prefered extensions. - - Compilation-generated object files should be of the ~.c.o~, ~.cxx.o~, ~.cc.o~ or ~.cpp.o~ corresponding to the correct extensions. - - All files should follow the UNIX® case formatting, including only lowercase alphabetical letters (~a-z~), underscores (~_~) and dots (~.~). Numbers are not allowed. - - Compilation-generated object files should have the same pre-extension basename as its the corresponding source file. - - Working on a *program*, every source file should have its own header file. The pre-extension basenames names should be corresponding. Orphan header files are tolerated. - - Source files should be composed of two parts: - - An index letter followed by an underscore (~_~). An index letters list should be found in an info comment under the main function. The index letter should be consistent. - - A single explicit word describing the file's purpose. - - Example of what a source file should look like: ~g_inventory.cxx~. Its corresponding header file should be ~g_inventory.hxx~ and its compilation-generated object file should be ~g_inventory.cxx.o~. In our case, ~g_~ may be described under the main function as gameplay-related. - - ~.txt~ format is pointless and forbidden. - - Don't forget a LICENSE and a README. Prefer org-mode or markdown for README if the project is going to be published on platforms such as GitLab or GitHub. Therefore extensions should be ~.org~ or ~.md~. You can add a copy of the README without extension properly formatted to be displayed in a terminal or platforms that do not handle org-mode or markdown. - -** Makefile - - The project should always contain at least one makefile. - - There can be more more than one makefile per projects but only one by subdirectories. - - The makefile should be in lowercases only with a capital "M": ~Makefile~. - - The main makefile should contain at least the 3 rules: - - ~all~ - - ~clean~ - - ~install~ - - Makefiles should not relink upon successful compilation. - - The main makefile should contain rules to compile any sub makefiles with the ~tools~ rule. - - All compiled binaries and libraries should be in the root of the project repository, next to the main makefile. - -** Compilation - - The compiler of choice for released binaries should be ~clang~ for C and ~clang++~ for C++. - - The program should compile with ~gcc~ or ~g++~ as well, so test those often. - - C standard of choice should be ~C89~. - - C++ standard of choice should be ~C++98~. - - ~C99~ is tolerated sometimes but ~C89~ should always be this first choice. - - Standard compiler flags should be: - - ~-std=c89~ for C or ~-std=c99~ for C++. - - ~-Wall~ - - ~-Wextra~ - - ~-Werror~ - - ~-pedantic~ - - When including external libraries, additional ~-Wno-~\x X flags may be added to mute external warnings generated by them, for example if one library uses a more recent standard. - - Example: ~-Wno-long-long~ if your library uses ~long long~'s. You will then have to be careful not using ~long long~'s in your code. - - Released binaries should never be compiled with ~-g~\x X options. - - The program should run without any issue with the ~-fsanitize=address~ or ~-fsanitize=memory~ options engaged. Test those often. - - Dynamic linking is prefearable. - -** Editors -No specific editor should be imposed over another, you should always pick the -one you feel the more comfortable with. However some of them are malicious -spyware that should never be recommanded. - -Here is a non-exhaustive list of recommanded or banished programs: - - - *Recommanded*: - - vi® / vim® and variants - - GNU Emacs® - - ee® - - joe® and variants - - *banished*: - - Microsoft™ VSCode® - - Microsoft™ Atom® - - JetBrains™ IntelliJ® variants - -** Version control - - Prefer ~fossil~ over ~git~. Using ~fossil~'s builtin function to mirror repository to ~git~ is fine. - - The repository should only contain files necessary to the compilation, execution or documentation of the program. - - The repository root should not contain anything else than the project's main makefile, LICENSE, README and subdirectories. diff --git a/docs/dergods_style_v1.ms b/docs/dergods_style_v1.ms new file mode 100644 index 0000000..fff2c0a --- /dev/null +++ b/docs/dergods_style_v1.ms @@ -0,0 +1,169 @@ +.defcolor blue rgb 0.1f 0.1f 1.0f +.defcolor bsdred rgb #990000 +.defcolor codered rgb #600000 +.defcolor grey rgb #aaaaaa +.defcolor black rgb #000000 +.color +.de bsdr +.gcolor bsdred +.. +.de endc +.gcolor +.. +.de xa +.XA \\$1 +.ps 12p +.B "\m[bsdred]\\$2\m[]" \\$3 \\$4 +.. +.de b +.B "\m[bsdred]\\$1\m[]" \\$2 \\$3 +.. +.de code +.gcolor bsdred +.CW \\$1 \\$2 \\$3 +.gcolor +.. +.de nh1 +.gcolor bsdred +.NH 1 +.ps 14p +\\$1 +.gcolor +.. +.de nh2 +.gcolor bsdred +.NH 2 +.ps 13p +\\$1 +.gcolor +.. +.de bu +.IP \(bu 2 +.. +. +. +. +. +.nr PS 12p +.nr PO 1.0i +.nr LL 6.5i +.RP no +.P1 +.ND +. +. +. +. +.gcolor black +.bsdr +.TL +.LG +.ps 17p +Dergods' Style and good practices for C/C++ projects +.endc +.AU +.ps 15p +Joe +.AI +42 Lyon Auvergne-Rhône-Alpes +. +. +.XS 1 +.ps 12p +.b "1. Introduction" +.xa 1 "2. Projects and version control" +.xa 1 " 2.1 Directories" +.XE +.bsdr +.PX +.endc +. +. +.nh1 "Introduction" +.PP +The following is a description of +.b "Dergods' Style" +code and project +formatting to put in use if you work on Dergods' Realm-related code or if you +just need a personal good-looking norm to improve your code readablity. It +is heavily inspired by +.b FreeBSD® 's +.pdfhref W -D \ +https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=0&\ +manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html \ +-A \m[black],\m[] \ +\f(CW\m[codered]style(9)\m[]\f[] +.gcolor +with some changes. +.nh1 "Projects and version control" +.nh2 "Directories" +.RS +.bu +Working on a +.b program : +.RS +.bu +All +.b source +and +.b "header files" +should be in the +.code src/ +directory. +.bu +Necessary +.b "media files" +such as images, sounds, fonts, etc... Necessary to the program execution +should be in the +.code media/ +directory. +.bu +Compilation-generated +.b "object files" +should be located in the +.code obj/ +directory. +.bu +.b Sub-programs +or +.b utilities +should be located in the +.code utils/ +directory. +.bu +Optional +.b "man page(s)" +can be made for the project and its specularities and should be located in the +.code man/ +directory. +.RE +.bu +Working on a +.b library : +.RS +.bu +All +.b "source files" +should be located in the +.code src/ +directory. +.bu +Compilation-generated +.b "object files" +should be located in the +.code obj/ +directory. +.bu +Non-optional +.b "man pages" +for every function intended to be used externally +should be located in the +.code man/ +directory. +.bu +.b "Header files" +should be located in the +.code include/ +directory. +.RE +.RE diff --git a/docs/dergods_style_v1.org b/docs/dergods_style_v1.org new file mode 100644 index 0000000..7d27312 --- /dev/null +++ b/docs/dergods_style_v1.org @@ -0,0 +1,104 @@ +#+TITLE: Dergods' Style and good practices for C/C++ +#+AUTHOR: Joe +#+DATE: v0.1 +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [a4paper] +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage[utf8]{inputenc} +#+LATEX_HEADER: \usepackage[dvipsnames]{xcolor} +#+LATEX_HEADER: \definecolor{mypink1}{rgb}{0.858, 0.188, 0.478} +#+LATEX_HEADER: \let\OldTexttt\texttt +#+LATEX_HEADER: \renewcommand{\texttt}[1]{% +#+LATEX_HEADER: \OldTexttt{% +#+LATEX_HEADER: \colorbox{gray}{% +#+LATEX_HEADER: \color{black} #1% +#+LATEX_HEADER: }% +#+LATEX_HEADER: }% +#+LATEX_HEADER: }% + +* Introduction +The following is a description of Dergods' Style code and project +formatting to put in use if you work on Dergods' Realm-related code or if you +just need a personnal good-looking norm to improve your code readablity. It +is heavily inspired by BSD [[https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html][style(9)]], +with some changes. + +* Projects and version control +** Directories + - Working on a *program*: + - All source and header files should be in the ~src/~ directory. + - Necessary media files such as images, sounds, fonts, etc... To the program execution should be in the ~media/~ directory. + - Compilation-generated object files should be located in the ~obj/~ directory. + - Sub-programs or utilities should be located in the ~tools/~ directory. + - An optional man page can be made for the program and should be located in the ~man/~ directory. + - Working on a *library*: + - All source files should be located in the ~src/~ directory. + - Compilation-generated object files should be located in the ~obj/~ directory. + - Non-optional man pages for every major function should be located in the ~man/~ directory. + - Header files should be located in the ~include/~ directory. + +** Files + - *C* sources and headers files should be of the ~.c~ and ~.h~ extensions. + - *C++* sources and header files should be of the corresponding ~.cxx~ / ~.hxx~ or ~.cc~ / ~.hh~ extensions unless the project is Microsoft™ Windows®-compatible only, then extensions should be ~.cpp~ / ~.hpp~. If the project is compatible with any UNIX®-like operating system, ~.cxx~ / ~.hxx~ or ~.cc~ / ~.hh~ should be the prefered extensions. + - Compilation-generated object files should be of the ~.c.o~, ~.cxx.o~, ~.cc.o~ or ~.cpp.o~ corresponding to the correct extensions. + - All files should follow the UNIX® case formatting, including only lowercase alphabetical letters (~a-z~), underscores (~_~) and dots (~.~). Numbers are not allowed. + - Compilation-generated object files should have the same pre-extension basename as its the corresponding source file. + - Working on a *program*, every source file should have its own header file. The pre-extension basenames names should be corresponding. Orphan header files are tolerated. + - Source files should be composed of two parts: + - An index letter followed by an underscore (~_~). An index letters list should be found in an info comment under the main function. The index letter should be consistent. + - A single explicit word describing the file's purpose. + - Example of what a source file should look like: ~g_inventory.cxx~. Its corresponding header file should be ~g_inventory.hxx~ and its compilation-generated object file should be ~g_inventory.cxx.o~. In our case, ~g_~ may be described under the main function as gameplay-related. + - ~.txt~ format is pointless and forbidden. + - Don't forget a LICENSE and a README. Prefer org-mode or markdown for README if the project is going to be published on platforms such as GitLab or GitHub. Therefore extensions should be ~.org~ or ~.md~. You can add a copy of the README without extension properly formatted to be displayed in a terminal or platforms that do not handle org-mode or markdown. + +** Makefile + - The project should always contain at least one makefile. + - There can be more more than one makefile per projects but only one by subdirectories. + - The makefile should be in lowercases only with a capital "M": ~Makefile~. + - The main makefile should contain at least the 3 rules: + - ~all~ + - ~clean~ + - ~install~ + - Makefiles should not relink upon successful compilation. + - The main makefile should contain rules to compile any sub makefiles with the ~tools~ rule. + - All compiled binaries and libraries should be in the root of the project repository, next to the main makefile. + +** Compilation + - The compiler of choice for released binaries should be ~clang~ for C and ~clang++~ for C++. + - The program should compile with ~gcc~ or ~g++~ as well, so test those often. + - C standard of choice should be ~C89~. + - C++ standard of choice should be ~C++98~. + - ~C99~ is tolerated sometimes but ~C89~ should always be this first choice. + - Standard compiler flags should be: + - ~-std=c89~ for C or ~-std=c99~ for C++. + - ~-Wall~ + - ~-Wextra~ + - ~-Werror~ + - ~-pedantic~ + - When including external libraries, additional ~-Wno-~\x X flags may be added to mute external warnings generated by them, for example if one library uses a more recent standard. + - Example: ~-Wno-long-long~ if your library uses ~long long~'s. You will then have to be careful not using ~long long~'s in your code. + - Released binaries should never be compiled with ~-g~\x X options. + - The program should run without any issue with the ~-fsanitize=address~ or ~-fsanitize=memory~ options engaged. Test those often. + - Dynamic linking is prefearable. + +** Editors +No specific editor should be imposed over another, you should always pick the +one you feel the more comfortable with. However some of them are malicious +spyware that should never be recommanded. + +Here is a non-exhaustive list of recommanded or banished programs: + + - *Recommanded*: + - vi® / vim® and variants + - GNU Emacs® + - ee® + - joe® and variants + - *banished*: + - Microsoft™ VSCode® + - Microsoft™ Atom® + - JetBrains™ IntelliJ® variants + +** Version control + - Prefer ~fossil~ over ~git~. Using ~fossil~'s builtin function to mirror repository to ~git~ is fine. + - The repository should only contain files necessary to the compilation, execution or documentation of the program. + - The repository root should not contain anything else than the project's main makefile, LICENSE, README and subdirectories. -- cgit v1.2.3