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

[Marvin Scholz]

ffmpeg | branch: master | Marvin Scholz <epirat07 at gmail.com> | Sat May 18 19:00:50 2024 +0200| [9cdd3cbe9b522431c121473a9ecf1d861efbc4b6] | committer: Marvin Scholz

doc/developer: add examples to clarify code style

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.

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=9cdd3cbe9b522431c121473a9ecf1d861efbc4b6
---

 doc/developer.texi | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 1 deletion(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index 78053a4623..a1bfe180c9 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}: