CodingStyle

↩ Back to Developer Documentation



Coding Style

Please follow the following rough rules when submitting code for inclusion in PA or committing code into Git. Although this list might appear massive I am still quite liberal in accepting patches that do not follow these rules. OTOH I am not your reindenting monkey, so please follow them, especially if your submissions are non-trivial!

And this is wrong:

    void bad_function(void)
    {
        if (a)
        {
            printf("Hello World!\n");
            a = 0;
        }
    }

Bad code:

    if (!braces_needed) {
        printf("This is superfluous and noisy.\n");
    }

This applies also if only one of the if-else branches have an one-line code block. Good code:

    if (!braces_needed)
        printf("This is compact and neat.\n");
    else {
        printf("Hello World!\n");
        a = 0;
    }

However, braces are welcome if there are multiple lines in a code block, even if the braces aren't technically necessary. Good code:

    if (a) {
        /* Imagine this comment explains something about using do_something(). */
        do_something(a);
    }

Also good code:

    if (a) {
        do_something(a, "This function call is split to two lines, because it's long. Other reasons: %s and %s",
                     one_reason, another_reason);
    }

and this is bad:

    int
    bad_function(void) {
    }

This bad:

    double sin (double x);

and this is bad:

    // This is a bad comment

Yes, the newest C iterations allow those comments. But they are ugly.

When a function declaration exceeds 128 charactes and wrapping is needed, please wrap the parameters using this style:

    pa_bluetooth_transport *pa_bluetooth_transport_new(pa_bluetooth_device *d, const char *owner, const char *path,
                                                       pa_bluetooth_profile_t p, const uint8_t *config, size_t size) {
        ...
    }

That is, wrap at 128 characters, and start the new line aligned with the opening parenthesis.

Bad code:

    void bad_code(int a, int b) {
        pa_assert(a > 47 && b != 0);

    }

Please note that pa_assert_se() is identical to pa_assert(), except that it is not optimized away if NDEBUG is defined. (se stands for side effect)

Yes, not all code that is part of PA right now follows these rules closely. This is mostly due to the fact that the formalization of these rules is newer then most of the code itself.


Localization

We have some rules for deciding whether a log message should be localized or not (again, the existing code base is mostly older than the rules, so there are a lot of places where the rules are not followed). From a message on the mailing list:

A few of us had an IRC conversation about whether or not to localise PulseAudio's log messages. The suggestion/outcome is to add localisation only if all of the following points are fulfilled:

  1. The message is of type "warning" or "error". (Debug and info levels are seldom exposed to end users.)

  2. The translator is likely to understand the sentence. (Otherwise we'll have a useless translation anyway.)

  3. It's at least remotely likely that someone will ever encounter it. (Otherwise we're just wasting translator's time.)

  4. The user is likely to be able to help himself, or at least be informed, after having read the message.

Example:

  • pa_log_warn(_("OK, so you are running PA in system mode. Please note that you most likely shouldn't be doing that.\n" (etc)

The above can remain localised.

  • pa_log_warn("Unable to set stop threshold: %s\n", pa_alsa_strerror(err));

The above should NOT be localised (fails both 2, 3, and 4.)

  • pa_log_info(_("Fresh high-resolution timers available! Bon appetit!"));

The above should be changed to NOT be localised. (fails at least 1. Maybe also 2 and 4.)


Indentation in Emacs

If you use Emacs, consider using this Elisp function for proper indentation:

(defun my-c-mode()
 "Lennart Poettering's C indentation"
 (message "Setting Lennart Poettering's C indentation...")
 (c-set-offset 'substatement-open 0)
 (c-set-offset 'statement-case-open 0)
 (c-set-offset 'case-label '+)
 (c-set-offset 'arglist-intro '++)
 (c-set-offset 'arglist-close 0)
 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
 (setq tab-width 8)
 (setq c-basic-offset 4)
 (c-toggle-hungry-state 1)
 (setq indent-tabs-mode nil))