Coding Style

Code formatting conventions

The code is written in K&R C style. That means the following:

• The control statements are formatted by putting space between the statement and parenthesis in the following way:

    for (i = 0; i < filter->input_count; i++) {

• The case statement is always located at the same level as the switch itself:

    switch (link->init_state) {
    case AVLINK_INIT:
        continue;
    case AVLINK_STARTINIT:
        av_log(filter, AV_LOG_INFO, "circular filter chain detected");
        return 0;

• Braces in function declarations are written on the new line:

    const char *avfilter_configuration(void)
    {
        return LIBAV_CONFIGURATION;
    }

• Do not check for NULL values by comparison, if (p) and if (!p) are correct; if (p == NULL) and if (p != NULL) are not.

• In case of a single-statement if, no curly braces are required:

    if (!pic || !picref)
        goto fail;

• Do not put spaces immediately inside parentheses. if (ret) is a valid style; if ( ret ) is not.

There are the following guidelines regarding the indentation in files:

• Indent size is 4.
• The TAB character is forbidden outside of Makefiles as is any form of trailing whitespace. Commits containing either will be rejected by the git repository.
• You should try to limit your code lines to 80 characters; however, do so if and only if this improves readability.

The presentation is one inspired by indent -i4 -kr -nut.

The main priority in Libav is simplicity and small code size in order to minimize the bug count.

Comments

Use the JavaDoc/Doxygen format (see examples below) so that code documentation can be generated automatically. All nontrivial functions should have a comment above them explaining what the function does, even if it is just one sentence. All structures and their member variables should be documented, too.

Avoid Qt-style and similar Doxygen syntax with ! in it, i.e. replace //! with /// and similar. Also @ syntax should be employed for markup commands, i.e. use @param and not \param.

/**
 * @file
 * MPEG codec.
 * @author ...
 */

/**
 * Summary sentence.
 * more text ...
 * ...
 */
typedef struct Foobar {
    int var1; /**< var1 description */
    int var2; ///< var2 description
    /** var3 description */
    int var3;
} Foobar;

/**
 * Summary sentence.
 * more text ...
 * ...
 * @param my_parameter description of my_parameter
 * @return return value description
 */
int myfunc(int my_parameter)
...

C language features

Libav is programmed in the ISO C90 language with a few additional features from ISO C99, namely:

• the inline keyword;

• // comments;

• designated struct initializers (struct s x = { .i = 17 };)

• compound literals (x = (struct s) { 17, 23 };)

These features are supported by all compilers we care about, so we will not accept patches to remove their use unless they absolutely do not impair clarity and performance.

All code must compile with recent versions of GCC and a number of other currently supported compilers. To ensure compatibility, please do not use additional C99 features or GCC extensions. Especially watch out for:

• mixing statements and declarations;

• long long (use int64_tv instead);

• attribute not protected by #ifdef GNUC or similar;

• GCC statement expressions ((x = ({ int y = 4; y; })).

Naming conventions

All names should be composed with underscores (_), not CamelCase. For example, avfilter_get_video_buffer is an acceptable function name and AVFilterGetVideo is not. The only exception are structure names; they should always be CamelCase.

There are the following conventions for naming variables and functions:

• For local variables no prefix is required.

• For file-scope variables and functions declared as static, no prefix is required.

• For variables and functions visible outside of file scope, but only used internally by a library, an ff_ prefix should be used, e.g. ff_w64_demuxer.

• For variables and functions visible outside of file scope, used internally across multiple libraries, use avpriv_ as prefix, for example, avpriv_aac_parse_header.

• For externally visible symbols, each library has its own prefix. Check the existing code and choose names accordingly.

Furthermore, name space reserved for the system should not be invaded. Identifiers ending in _t are reserved by POSIX. Also avoid names starting with or _ followed by an uppercase letter as they are reserved by the C standard. Names starting with _ are reserved at the file level and may not be used for externally visible symbols. If in doubt, just avoid names starting with _ altogether.

Miscellaneous conventions

• fprintf and printf are forbidden in libraries, please use av_log() instead.

• Casts should be used only when necessary.
• Unneeded parentheses should also be avoided if they do not make the code easier to understand.

Additional information

The following subpages provide additional information regarding the coding style used in Libav.

CategoryWIP CategoryHowTo