[FFmpeg-devel] [PATCH] doc/developer: add examples to clarify code style

[Marvin Scholz]

Given the frequency that new developers, myself included, get the
code style wrong, it is useful to add some examples to clarify how
things should be done.
---
 doc/developer.texi | 57 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index 63835dfa06..d7bf3f9cb8 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -115,7 +115,7 @@ Objective-C where required for interacting with macOS-specific interfaces.
 
 @section Code formatting conventions
 
-There are the following guidelines regarding the indentation in files:
+There are the following guidelines regarding the code style in files:
 
 @itemize @bullet
 @item
@@ -135,6 +135,61 @@ K&R coding style is used.
 @end itemize
 The presentation is one inspired by 'indent -i4 -kr -nut'.
 
+ at subsection Examples
+Some notable examples to illustrate common code style in FFmpeg:
+
+ at itemize @bullet
+
+ at item
+Spaces around @code{if}/@code{do}/@code{while}/@code{for} conditions and assigments:
+
+ at example c
+if (condition)
+    av_foo();
+ at end example
+
+ at example c
+for (size_t i = 0; i < len; i++)
+    av_bar(i);
+ at end example
+
+ at example c
+size_t size = 0;
+ at end example
+
+However no spaces between the parentheses and condition, unless it helps
+readability of complex conditions, so the following should not be done:
+
+ at example c
+// Wrong:
+if ( cond )
+    av_foo();
+ at end example
+
+ at item
+No unnecessary parentheses, unless it helps readability:
+
+ at example c
+flags = s->mb_x ? RIGHT_EDGE : LEFT_EDGE | RIGHT_EDGE;
+ at end example
+
+ at item
+No braces around single-line blocks:
+
+ at example c
+if (bits_pixel == 24)
+    avctx->pix_fmt = AV_PIX_FMT_BGR24;
+else if (bits_pixel == 8)
+    avctx->pix_fmt = AV_PIX_FMT_GRAY8;
+else @{
+    av_log(avctx, AV_LOG_ERROR, "Invalid pixel format.\n");
+    return AVERROR_INVALIDDATA;
+@}
+ at end example
+
+ at end itemize
+
+
 @subsection Vim configuration
 In order to configure Vim to follow FFmpeg formatting conventions, paste
 the following snippet into your @file{.vimrc}:

base-commit: 86e418ffd7bbdc0530e1e4d5bd7534b6e03b5b05
-- 
2.39.3 (Apple Git-145)