docs/coding-style.md


Log

Author Commit Date CI Message
Patrick Steinhardt ffb6a576 2020-04-04T14:36:27 docs: add documentation for our coding style For years, we've repeatedly had confusion about what our actual coding style is not only for newcomers, but also across the core contributors. This can mostly be attributed to the fact that we do not have any coding conventions written down. This is now a thing of the past with the introduction of a new document that gives an initial overview of our style and most important best practices for both our C codebase as well as for CMake. While the proposed coding style for our C codebase should be rather uncontroversial, the coding style for CMake might be. This can be attributed to multiple facts. First, the CMake code base doesn't really have any uniform coding style and is quite outdated in a lot of places. Second, the proposed coding style actually breaks with our existing one: we currently use all-uppercase function names and variables, but the documented coding style says we use all-lowercase function names but all-uppercase variables. It's common practice in CMake to write variables in all upper-case, and in fact all variables made available by CMake are exactly that. As variables are case-sensitive in CMake, we cannot and shouldn't break with this. In contrast, function calls are case insensitive, and modern CMake always uses all-lowercase ones. I argue we should do the same to get in line with other codebases and to reduce the likelihood of repetitive strain injuries. So especially for CMake, the proposed coding style says something we don't have yet. I'm fine with that, as the document explicitly says that it's what we want to have and not what we have right now.