summaryrefslogtreecommitdiff
path: root/doc/coding-style.txt
diff options
context:
space:
mode:
authorGuillem Jover <guillem@debian.org>2016-08-28 18:59:03 +0200
committerGuillem Jover <guillem@debian.org>2016-10-29 16:02:49 +0200
commit9aa458e8a34bdef30538a84e6cf74bc4ac5d4d6c (patch)
tree1487e2cf26e3e3749ea131e5e7936429b9f07132 /doc/coding-style.txt
parent758ecf7fe1cb15abb87c796fb3a7f15933c56f67 (diff)
downloaddpkg-9aa458e8a34bdef30538a84e6cf74bc4ac5d4d6c.tar.gz
build: Fix M4sh/Autoconf coding style
Indent the code in a way that makes it easier to follow. Use AS_IF instead of shell constructs. Quote all autoconf macro arguments. Add a new section to coding-style.txt describing M4sh/Autoconf.
Diffstat (limited to 'doc/coding-style.txt')
-rw-r--r--doc/coding-style.txt54
1 files changed, 54 insertions, 0 deletions
diff --git a/doc/coding-style.txt b/doc/coding-style.txt
index 06bf3b792..0e07806e4 100644
--- a/doc/coding-style.txt
+++ b/doc/coding-style.txt
@@ -14,6 +14,60 @@ Every new feature, option or behavior change needs to be documented with
the version introducing the change.
+Dpkg M4sh/Autoconf coding style 1016-09-05
+===============================
+
+General
+~~~~~~~
+
+All dpkg specific macros need to be prefixed with «DPKG_». Complex checks
+should be defined as new macros under m4/dpkg-<name>.m4, and those used
+in configure.ac which should look pretty simple.
+
+Quoting and indentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Code and arguments that wrap into the next line are indented by two spaces.
+
+In principle all macro argument should always be quoted. Which gives brings
+one of the biggest readability issues with M4sh/Autoconf code, the amount of
+consecutive quotes and parenthesis pairs, which can make it very hard to
+notice if they are unbalanced. To avoid this we use a style that tries to
+avoid more than two consecutive blocks of «])».
+
+We can either use a style resembling very simple function calls, when the
+arguments are as well very simple, such as:
+
+ AC_DEFINE_UNQUOTED([SOME_VARIABLE],
+ [SOME_CONCOCTED_WAY_TO_GET_A_VALUE],
+ [Some descriptive text here])
+
+ AS_CASE([condition],
+ [case-a], [do-a],
+ [case-b], [do-b])
+
+Or one resembling curly-braced C-style blocks, such as this:
+
+ AS_IF([condition], [
+ DO_SOMETHING([here])
+ ], [
+ DO_OTHERWISE([there])
+ ])
+
+Except for AC_ARG_WITH, AC_ARG_ENABLE and AM_CONDITIONAL which need their
+second argument quoted tightly surrounding the code, like this:
+
+ AC_ARG_ENABLE([feature],
+ [AS_HELP_STRING([--disable-feature], [Disable feature])],
+ [], [enable_feature="yes"])
+
+ AM_CONDITIONAL([HAVE_SOME_FEATURE],
+ [test "x$ac_cv_have_some_feature" = "xyes" && \
+ test "x$ac_cv_have_some_feature" = "xyes"])
+
+or the output will get messed up.
+
+
Dpkg C/C++ coding style 2016-01-29
=======================