[FFmpeg-devel] [PATCH v2 1/2] 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 | 101 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 1 deletion(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index 41b21938ef..ea143549b4 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,105 @@ 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
+Space around assignments and after
+ at code{if}/@code{do}/@code{while}/@code{for} keywords:
+
+ at example c, good
+// Good
+if (condition)
+    av_foo();
+ at end example
+
+ at example c, good
+// Good
+for (size_t i = 0; i < len; i++)
+    av_bar(i);
+ at end example
+
+ at example c, good
+// Good
+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, bad
+// Bad style
+if ( condition )
+    av_foo();
+ at end example
+
+ at item
+No unnecessary parentheses, unless it helps readability:
+
+ at example c, good
+// Good
+int fields = ilace ? 2 : 1;
+ at end example
+
+ at item
+No braces around single-line blocks:
+
+ at example c, good
+// Good
+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 item
+Avoid assignments in conditions where it makes sense:
+
+ at example c, good
+// Good
+video_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64)
+if (!video_enc->chroma_intra_matrix)
+    return AVERROR(ENOMEM);
+ at end example
+
+ at example c, bad
+// Bad style
+if (!(video_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64)))
+    return AVERROR(ENOMEM);
+ at end example
+
+ at example c, good
+// Ok
+while ((entry = av_dict_iterate(options, entry)))
+    av_log(ctx, AV_LOG_INFO, "Item '%s': '%s'\n", entry->key, entry->value);
+ at end example
+
+ at item
+When declaring a pointer variable, the @code{*} goes with the variable not the type:
+
+ at example c, good
+// Good
+AVStream *stream;
+ at end example
+
+ at example c, bad
+// Bad style
+AVStream* stream;
+ at end example
+
+ at end itemize
+
+If you work on a file that does not follow these guidelines consistently,
+change the parts that you are editing to follow these guidelines but do
+not make unrelated changes in the file to make it conform to these.
+
 @subsection Vim configuration
 In order to configure Vim to follow FFmpeg formatting conventions, paste
 the following snippet into your @file{.vimrc}:

base-commit: 6229e4ac425b4566446edefb67d5c225eb397b58
-- 
2.39.3 (Apple Git-146)