Unified · Split
| @@ -45,48 +45,61 @@ mailing list. · 44 unmodified lines | |||
| 45 | @anchor{Coding Rules} | 45 | @anchor{Coding Rules} |
| 46 | @section Coding Rules | 46 | @section Coding Rules |
| 47 | 47 | ||
| 48 | Libav is programmed in the ISO C90 language with a few additional | 48 | @subsection Code formatting conventions |
| 49 | features from ISO C99, namely: | 49 | The code is written in K&R C style. That means the following: |
| 50 | @itemize @bullet | 50 | @itemize @bullet |
| 51 | @item | 51 | @item |
| 52 | the @samp{inline} keyword; | 52 | The control statements are formatted by putting space betwen the statement and parenthesis |
| 53 | in the following way: | ||
| 54 | @example | ||
| 55 | for (i = 0; i < filter->input_count; i ++) @{ | ||
| 56 | @end example | ||
| 53 | @item | 57 | @item |
| 54 | @samp{//} comments; | 58 | The case statement is always located at the same level as the switch itself: |
| 59 | @example | ||
| 60 | switch (link->init_state) @{ | ||
| 61 | case AVLINK_INIT: | ||
| 62 | continue; | ||
| 63 | case AVLINK_STARTINIT: | ||
| 64 | av_log(filter, AV_LOG_INFO, "circular filter chain detected"); | ||
| 65 | return 0; | ||
| 66 | @end example | ||
| 55 | @item | 67 | @item |
| 56 | designated struct initializers (@samp{struct s x = @{ .i = 17 @};}) | 68 | Braces in function declarations are written on the new line: |
| 69 | @example | ||
| 70 | const char *avfilter_configuration(void) | ||
| 71 | @{ | ||
| 72 | return LIBAV_CONFIGURATION; | ||
| 73 | @} | ||
| 74 | @end example | ||
| 57 | @item | 75 | @item |
| 58 | compound literals (@samp{x = (struct s) @{ 17, 23 @};}) | 76 | In case of a single-statement if, no curly braces are required: |
| 77 | @example | ||
| 78 | if (!pic || !picref) | ||
| 79 | goto fail; | ||
| 80 | @end example | ||
| 81 | @item | ||
| 82 | Do not put spaces immediately inside parenthesis. @samp{if (ret)} is a valid style; @samp{if ( ret )} is not. | ||
| 59 | @end itemize | 83 | @end itemize |
| 60 | 84 | ||
| 61 | These features are supported by all compilers we care about, so we will not | 85 | There are the following guidelines regarding the indentation in files: |
| 62 | accept patches to remove their use unless they absolutely do not impair | ||
| 63 | clarity and performance. | ||
| 64 | |||
| 65 | All code must compile with recent versions of GCC and a number of other | ||
| 66 | currently supported compilers. To ensure compatibility, please do not use | ||
| 67 | additional C99 features or GCC extensions. Especially watch out for: | ||
| 68 | @itemize @bullet | 86 | @itemize @bullet |
| 69 | @item | 87 | @item |
| 70 | mixing statements and declarations; | ||
| 71 | @item | ||
| 72 | @samp{long long} (use @samp{int64_t} instead); | ||
| 73 | @item | ||
| 74 | @samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar; | ||
| 75 | @item | ||
| 76 | GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}). | ||
| 77 | @end itemize | ||
| 78 | |||
| 79 | Indent size is 4. | 88 | Indent size is 4. |
| 80 | The presentation is one inspired by 'indent -i4 -kr -nut'. | 89 | @item |
| 81 | The TAB character is forbidden outside of Makefiles as is any | 90 | The TAB character is forbidden outside of Makefiles as is any |
| 82 | form of trailing whitespace. Commits containing either will be | 91 | form of trailing whitespace. Commits containing either will be |
| 83 | rejected by the git repository. | 92 | rejected by the git repository. |
| 93 | @item | ||
| 94 | You should try to limit your code lines to 80 characters; however, do so if and only if this improves readability. | ||
| 95 | @end itemize | ||
| 96 | The presentation is one inspired by 'indent -i4 -kr -nut'. | ||
| 84 | 97 | ||
| 85 | The main priority in Libav is simplicity and small code size in order to | 98 | The main priority in Libav is simplicity and small code size in order to |
| 86 | minimize the bug count. | 99 | minimize the bug count. |
| 87 | 100 | ||
| 88 | Comments: Use the JavaDoc/Doxygen | 101 | @subsection Comments |
| 89 | format (see examples below) so that code documentation | 102 | Use the JavaDoc/Doxygen format (see examples below) so that code documentation |
| 90 | can be generated automatically. All nontrivial functions should have a comment | 103 | can be generated automatically. All nontrivial functions should have a comment |
| 91 | above them explaining what the function does, even if it is just one sentence. | 104 | above them explaining what the function does, even if it is just one sentence. |
| 92 | All structures and their member variables should be documented, too. | 105 | All structures and their member variables should be documented, too. |
| @@ -120,11 +133,69 @@ int myfunc(int my_parameter) · 27 unmodified lines | |||
| 120 | ... | 133 | ... |
| 121 | @end example | 134 | @end example |
| 122 | 135 | ||
| 136 | @subsection C language features | ||
| 137 | |||
| 138 | Libav is programmed in the ISO C90 language with a few additional | ||
| 139 | features from ISO C99, namely: | ||
| 140 | @itemize @bullet | ||
| 141 | @item | ||
| 142 | the @samp{inline} keyword; | ||
| 143 | @item | ||
| 144 | @samp{//} comments; | ||
| 145 | @item | ||
| 146 | designated struct initializers (@samp{struct s x = @{ .i = 17 @};}) | ||
| 147 | @item | ||
| 148 | compound literals (@samp{x = (struct s) @{ 17, 23 @};}) | ||
| 149 | @end itemize | ||
| 150 | |||
| 151 | These features are supported by all compilers we care about, so we will not | ||
| 152 | accept patches to remove their use unless they absolutely do not impair | ||
| 153 | clarity and performance. | ||
| 154 | |||
| 155 | All code must compile with recent versions of GCC and a number of other | ||
| 156 | currently supported compilers. To ensure compatibility, please do not use | ||
| 157 | additional C99 features or GCC extensions. Especially watch out for: | ||
| 158 | @itemize @bullet | ||
| 159 | @item | ||
| 160 | mixing statements and declarations; | ||
| 161 | @item | ||
| 162 | @samp{long long} (use @samp{int64_t} instead); | ||
| 163 | @item | ||
| 164 | @samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar; | ||
| 165 | @item | ||
| 166 | GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}). | ||
| 167 | @end itemize | ||
| 168 | |||
| 169 | @subsection Naming conventions | ||
| 170 | All names are using underscores (_), not CamelCase. For example, @samp{avfilter_get_video_buffer} is | ||
| 171 | a valid function name and @samp{AVFilterGetVideo} is not. The only exception from this are structure names; | ||
| 172 | they should always be in the CamelCase | ||
| 173 | |||
| 174 | There are following conventions for naming variables and functions: | ||
| 175 | @itemize @bullet | ||
| 176 | @item | ||
| 177 | For local variables no prefix is required. | ||
| 178 | @item | ||
| 179 | For variables and functions declared as @code{static} no prefixes are required. | ||
| 180 | @item | ||
| 181 | For variables and functions used internally by the library, @code{ff_} prefix should be used. | ||
| 182 | For example, @samp{ff_w64_demuxer}. | ||
| 183 | @item | ||
| 184 | For variables and functions used internally across multiple libraries, use @code{avpriv_}. For example, | ||
| 185 | @samp{avpriv_aac_parse_header}. | ||
| 186 | @item | ||
| 187 | For exported names, each library has its own prefixes. Just check the existing code and name accordingly. | ||
| 188 | @end itemize | ||
| 189 | |||
| 190 | @subsection Miscellanous conventions | ||
| 191 | @itemize @bullet | ||
| 192 | @item | ||
| 123 | fprintf and printf are forbidden in libavformat and libavcodec, | 193 | fprintf and printf are forbidden in libavformat and libavcodec, |
| 124 | please use av_log() instead. | 194 | please use av_log() instead. |
| 125 | 195 | @item | |
| 126 | Casts should be used only when necessary. Unneeded parentheses | 196 | Casts should be used only when necessary. Unneeded parentheses |
| 127 | should also be avoided if they don't make the code easier to understand. | 197 | should also be avoided if they don't make the code easier to understand. |
| 198 | @end itemize | ||
| 128 | 199 | ||
| 129 | @section Development Policy | 200 | @section Development Policy |
| 130 | 201 | ||