thodg/libgit2/docs

Diff

  • Show log

    Commit

  • Hash : ffb6a576
    Author : Patrick Steinhardt
    Date : 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.

kmx.io     mail     discord kmxgit v0.4.0