You Can't Just Go and Buy a Sheep
Prologue
Some organizations that program microcontrollers have their own internal standard for formatting C-sources. As a rule, there are usually reasonable points. However, in this text I have listed the most ridiculous and absurd requirements and recommendations for formatting sources that are actually present in modern Russian electronic organizations that program microcontrollers.
These are the requirements of the category, to put it mildly, “For what?”. Here are literally a few real life examples. This is simply a dictatorship of the absurd, a parade of absurdity.
1—Prohibition installation of programs, ban opening the device manager, ban opening the task manager, ban registering the PATH variable on local PCs. Everything is only through the department manager's password.
2—Collect code only with a mouse from under the GUI-IDE (IAR or KEIL) and no build scripts (Make, CMake)!
3—Strict rules for indenting code and in general artificially fictitious code formatting that even with options clang-format or GNU-indent It is impossible to set. Only manual indentation!
4—Strict rules for formatting the text header before each function. God forbid you put an extra space!
5–Write text comments for each line of C code. It doesn't matter that the names of variables and functions are clear anyway.
6–Strict prohibition of use bit fields in the C programming language.
7–Strict prohibition on use associations V (union) Si .
8–Strict prohibition on use transfers (enum) in the C programming language.
9– Each configuration constant must have a comment with “Valid values”, which describes the set of possible values of this constant. Enumerations (enum) are prohibited, so you have to find a way around it somehow, through text comments.
10— Prohibition on using standard data types from files <stdint.h> <stdbool.h> (bool, uint32_t, int8_t, etc.)
11 — The first line of the file must contain the comment “start of file“
12–The penultimate line of the source file must contain a comment
“//****end of file*******”
As the author of the requirement told me: “This is so that the code can be sent as a message in a text messenger and it would be clear where the file ends.” How do you like this argument?
13 — Store the linker settings directly in the project folder. And so for each project with the same microcontroller. This results in duplication of the linker configs.
14– Using third-party library code is prohibited! No FreeRTOS, CMSIS, FatFs, HAL from the official microcontroller manufacturer! Any Third Party is prohibited!
15– All function arguments must be listed “in a column”.
16– For all declarations of global functions in the h-file the keyword extern is required! It does not matter that the code is compiled and works without extern.
17– The order of function declarations must match the order of function definitions. Just an unnecessary rule to waste more time.
18– All comments must begin with //~ and nothing else!
We will come up with our own corporate style for one-line comments. This is how we promote our brand.
19–Multi-line comments are prohibited /**/
20— The strictest prohibition of using functions from <math.h> [sin() cos() log10() fabs() и т. п.]!
21—Next to global variables, write a comment: “Look, these are global variables!”
22 — At the top of the file, write the file name as a comment. It doesn't matter that it is already visible in the file system.
23—At the end of each function, write a comment: “Look, this is the end of the function!” Otherwise, it’s not clear from the curly bracket…
24 — All static functions should be written at the end of the file. And then the prototypes of these functions should be written at the top a second time. Apparently, to spend more time on work and to increase the probability of desynchronizing the names of variables in prototypes and definitions.
You understand that all of this is just requirements for the sake of requirements. It looks more like quotes from the Turkmen president than some kind of reasonable development standard.
I don't think I need to explain what this is monkey bureaucracy only slows down the achievement of real functional results in the development of system software.
At the same time, I will add that in such meticulously “demanding” organizations, as a rule, it is not customary to assemble projects from scripts, to cover the code with unit tests, there is no NVRAM in the firmware, there is no UART-CLI in the firmware for debugging the functionality, there is no build server, not even in Jenkins, there is no bootloader in the firmware and many other things that, according to common sense, should actually be done first of all… Do you understand?…
Sometimes all this legislation looks like observing the rules of surgical sterility, stables! Yes.. That's right… Excessive requirements for code formatting are similar to some kind of military IT-drill.
Results
Please explain to me what is the deep meaning of the above mentioned requirements for the code?
Personally, I have absolutely nothing against a list of requirements for the code. It's even great that there is stable, predictable work around this whole circus.
However, it would be normal if these demands were accompanied by a short, clear and transparent argumentation for why they are being so zealously pushed. And that priorities were set as to which demands are more important and which are just…
The truth is that each code requirement shifts the software project delivery date by 10-15%. When an organization has, for example, 463 C code formatting rules, the development time increases by 46.3 times. Do you understand?
Tell me if I could soldier Kurchatov Igor Vasilievich, to make an atomic bomb from scratch in 4 years with such bureaucracy? I think the answer is clear to everyone…
Write in the comments what strange requirements for formatting source codes exist in your organization. I'm just wondering if it's possible to come up with something more absurd in C than what I listed here.
Links
