summaryrefslogtreecommitdiff
path: root/libs/cairo-1.16.0/CODING_STYLE
diff options
context:
space:
mode:
authorsanine <sanine.not@pm.me>2023-02-12 23:53:22 -0600
committersanine <sanine.not@pm.me>2023-02-12 23:53:22 -0600
commitf1fe73d1909a2448a004a88362a1a532d0d4f7c3 (patch)
treeab37ae3837e2f858de2932bcee9f26e69fab3db1 /libs/cairo-1.16.0/CODING_STYLE
parentf567ea1e2798fd3156a416e61f083ea3e6b95719 (diff)
switch to tinyobj and nanovg from assimp and cairo
Diffstat (limited to 'libs/cairo-1.16.0/CODING_STYLE')
-rw-r--r--libs/cairo-1.16.0/CODING_STYLE291
1 files changed, 0 insertions, 291 deletions
diff --git a/libs/cairo-1.16.0/CODING_STYLE b/libs/cairo-1.16.0/CODING_STYLE
deleted file mode 100644
index 95ceac0..0000000
--- a/libs/cairo-1.16.0/CODING_STYLE
+++ /dev/null
@@ -1,291 +0,0 @@
-Cairo coding style.
-
-This document is intended to be a short description of the preferred
-coding style for the cairo source code. Good style requires good
-taste, which means this can't all be reduced to automated rules, and
-there are exceptions.
-
-We want the code to be easy to understand and maintain, and consistent
-style plays an important part in that, even if some of the specific
-details seem trivial. If nothing else, this document gives a place to
-put consistent answers for issues that would otherwise be arbitrary.
-
-Most of the guidelines here are demonstrated by examples, (which means
-this document is quicker to read than it might appear given its
-length). Most of the examples are positive examples that you should
-imitate. The few negative examples are clearly marked with a comment
-of /* Yuck! */. Please don't submit code to cairo that looks like any
-of these.
-
-Indentation
------------
-Each new level is indented 4 more spaces than the previous level:
-
- if (condition)
- do_something ();
-
-This may be achieved with space characters or a combination of tab
-characters and space characters. It may not be achieved with tab
-characters exclusively (see below).
-
-Tab characters
---------------
-The tab character must always be interpreted according to its
-traditional meaning:
-
- Advance to the next column which is a multiple of 8.
-
-With this definition, even levels of indentation can be achieved with
-a sequence of tab characters, while odd levels of indentation may
-begin with a sequence of tab character but must end with 4 space
-characters.
-
-Some programmers have been misled by certain text editors into
-thinking that 4-space indentation can be achieved with tab characters
-exclusively by changing the meaning of tab character to be "advance to
-the next column which is a multiple of 4". Code formatted in this way,
-making an assumption of a fictitious 4-character-tab will not be
-accepted into cairo.
-
-The rationale here is that tabs are used in the code for lining things
-up other than indentation, (see the Whitespace section below), and
-changing the interpretation of tab from its traditional meaning will
-break this alignment.
-
-Braces
-------
-Most of the code in cairo uses bracing in the style of K&R:
-
- if (condition) {
- do_this ();
- do_that ();
- } else {
- do_the_other ();
- }
-
-but some of the code uses an alternate style:
-
- if (condition)
- {
- do_this ();
- do_that ();
- }
- else
- {
- do_the_other ();
- }
-
-and that seems just fine. We won't lay down any strict rule on this
-point, (though there should be some local consistency). If you came
-here hoping to find some guidance, then use the first form above.
-
-If all of the substatements of an if statement are single statements,
-the optional braces should not usually appear:
-
- if (condition)
- do_this ();
- else
- do_that ();
-
-But the braces are mandatory when mixing single statement and compound
-statements in the various clauses. For example, do not do this:
-
- if (condition) {
- do_this ();
- do_that ();
- } else /* Yuck! */
- do_the_other ();
-
-And of course, there are exceptions for when the code just looks
-better with the braces:
-
- if (condition) {
- /* Note that we have to be careful here. */
- do_something_dangerous (with_care);
- }
-
- if (condition &&
- other_condition &&
- yet_another)
- {
- do_something ();
- }
-
-And note that this last example also shows a situation in which the
-opening brace really needs to be on its own line. The following looks awful:
-
- if (condition &&
- other_condition &&
- yet_another) { /* Yuck! */
- do_something ();
- }
-
-As we said above, legible code that is easy to understand and maintain
-is the goal, not adherence to strict rules.
-
-Whitespace
-----------
-Separate logically distinct chunks with a single newline. This
-obviously applies between functions, but also applies within a
-function or block and can even be used to good effect within a
-structure definition:
-
- struct _cairo_gstate {
- cairo_operator_t op;
-
- double tolerance;
-
- /* stroke style */
- double line_width;
- cairo_line_cap_t line_cap;
- cairo_line_join_t line_join;
- double miter_limit;
-
- cairo_fill_rule_t fill_rule;
-
- double *dash;
- int num_dashes;
- double dash_offset;
-
- ...
- }
-
-Use a single space before a left parenthesis, except where the
-standard will not allow it, (eg. when defining a parameterized macro).
-
-Don't eliminate newlines just because things would still fit on one
-line. This breaks the expected visual structure of the code making it
-much harder to read and understand:
-
- if (condition) foo (); else bar (); /* Yuck! */
-
-Do eliminate trailing whitespace (space or tab characters) on any
-line. Also, avoid putting initial or final blank lines into any file,
-and never use multiple blank lines instead of a single blank line.
-
-Do enable the default git pre-commit hook that detect trailing
-whitespace for you and help you to avoid corrupting cairo's tree with
-it. Do that as follows:
-
- chmod a+x .git/hooks/pre-commit
-
-You might also find the git-stripspace utility helpful which acts as a
-filter to remove trailing whitespace as well as initial, final, and
-duplicate blank lines.
-
-As a special case of the bracing and whitespace guidelines, function
-definitions should always take the following form:
-
- void
- my_function (argument)
- {
- do_my_things ();
- }
-
-And function prototypes should similarly have the return type (and
-associated specifiers and qualifiers) on a line above the function, so
-that the function name is flush left.
-
-Break up long lines (> ~80 characters) and use whitespace to align
-things nicely. For example the arguments in a long list to a function
-call should all be aligned with each other:
-
- align_function_arguments (argument_the_first,
- argument_the_second,
- argument_the_third);
-
-And as a special rule, in a function prototype, (as well as in the
-definition), whitespace should be inserted between the parameter types
-and names so that the names are aligned:
-
- void
- align_parameter_names_in_prototypes (const char *char_star_arg,
- int int_arg,
- double *double_star_arg,
- double double_arg);
-
-Note that parameters with a * prefix are aligned one character to the
-left so that the actual names are aligned.
-
-Managing nested blocks
-----------------------
-Long blocks that are deeply nested make the code very hard to
-read. Fortunately such blocks often indicate logically distinct chunks
-of functionality that are begging to be split into their own
-functions. Please listen to the blocks when they beg.
-
-In other cases, gratuitous nesting comes about because the primary
-functionality gets buried in a nested block rather than living at the
-primary level where it belongs. Consider the following:
-
- foo = malloc (sizeof (foo_t));
- if (foo) { /* Yuck! */
- ...
- /* lots of code to initialize foo */
- ...
- return SUCCESS;
- }
- return FAILURE;
-
-This kind of gratuitous nesting can be avoided by following a pattern
-of handling exceptional cases early and returning:
-
- foo = malloc (sizeof (foo_t));
- if (foo == NULL)
- return FAILURE;
-
- ...
- /* lots of code to initialize foo */
- ...
- return SUCCESS;
-
-The return statement is often the best thing to use in a pattern like
-this. If it's not available due to additional nesting above which
-require some cleanup after the current block, then consider splitting
-the current block into a new function before using goto.
-
-Memory allocation
------------------
-
-Because much of cairo's data consists of dynamically allocated arrays,
-it's very easy to introduce integer overflow issues whenever malloc()
-is called. Use the _cairo_malloc2(), _cairo_malloc3(), and
-_cairo_malloc2_add1 macros to avoid these cases; these macros check
-for overflow and will return NULL in that case.
-
- malloc (n * size) => _cairo_malloc_ab (n, size)
- e.g. malloc (num_elts * sizeof(some_type)) =>
- _cairo_malloc2 (num_elts, sizeof(some_type))
-
- malloc (a * b * size) => _cairo_malloc_abc (a, b, size)
- e.g. malloc (width * height * 4) =>
- _cairo_malloc3 (width, height, 4)
-
- malloc (n * size + k) => _cairo_malloc_ab_plus_c (n, size, k)
- e.g. malloc (num * sizeof(entry) + sizeof(header)) =>
- _cairo_malloc2k (num, sizeof(entry), sizeof(header))
-
-In general, be wary of performing any arithmetic operations in an
-argument to malloc. You should explicitly check for integer overflow
-yourself in any more complex situations.
-
-Mode lines
-----------
-
-So given the rules above, what is the best way to simplify one's life as
-a code monkey? Get your editor to do most of the tedious work of
-beautifying your code!
-
-As a reward for reading this far, here are some mode lines for the more
-popular editors:
-/*
- * vim:sw=4:sts=4:ts=8:tw=78:fo=tcroq:cindent:cino=\:0,(0
- * vim:isk=a-z,A-Z,48-57,_,.,-,>
- */
-
-
-TODO
-----
-
-Write rules for common editors to use this style. Also cleanup/unify
-the modelines in the source files.