From patchwork Sat May 18 17:00:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marvin Scholz X-Patchwork-Id: 51571 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a59:9fc3:0:b0:48e:c0f8:d0de with SMTP id k3csp100288vqy; Fri, 13 Sep 2024 16:19:11 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCV3qHyjWC/jfayIHV0HEFwas++ILT4F+ZkZzZa1HTU8Z/0+qQn4+7rv0+JT4MYUS0FDIYt3aU4m7JHQZM+bjijq@gmail.com X-Google-Smtp-Source: AGHT+IFloXgxuoYDNAaAnMft3PREjZmhJKlyfHxNsf8D6eUnLw7FV5z184Gx98jlRt/Rj/CCf9Aj X-Received: by 2002:a2e:be0f:0:b0:2ef:2c40:dd67 with SMTP id 38308e7fff4ca-2f787c1ad86mr31244191fa.3.1726269550723; Fri, 13 Sep 2024 16:19:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1726269550; cv=none; d=google.com; s=arc-20240605; b=d1QiBZynjHBpLB4YZFRO3q1ouA2jqWf7HhRWFP1r2/kJXGHrFpKPHpfWdvf56yE8Ye TKn/GBx8oc2awifv+AzndwxNLMsPIerrsIXYupMiBRFVW9njUFOFjpG0nGr3ecagJ/iI 4jk+QKFHTShlhNXvVZLUTpOoJG49xDA7F95CDo0arciQFBSRvdD9LTgO+ACUH0f6caed CYFjFExtBhbCwfqBNi6ewwvl16Xv3lXWD6/j89CCDxczHg2DOkDPy4h0oJF1cU/BgLPr IkM4+fhYhNBc5WvXSFo+PMRw6uqa3A05OVPAQbkC3YogikW/0IxOKg0sb1DWk4Bj0ASi mQIA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=sender:errors-to:content-transfer-encoding:mime-version:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:date:from:to:message-id:dkim-signature :delivered-to; bh=jLGr6onnoccBWHDRSaRvHapaTGNR70HuWgz4ruG7nN0=; fh=5IeVwzS1vbVKjIV8MP3mnmnRtZGb8uteQ9r4QD2keV0=; b=grVtEpe/+ebmQAtCOvyeBDm+3hHdprATUj+ZvhoM5wLVBI/2DANBOKAp7sens3FQIj GaY1hit7+78lFDAthd9skTUbpONUMlim5d7eC2Qqsn+B+8hlVHnqTLlWI6EXXFnxIw9p 5vc5hKbbD6aGqH3pPHFJGO9b17C4YyYBWQXy/iSrgLhl6YgYeecEIDzSwfEPUsFj48Nr xP/Rsbh2zTj9IlTT692LreR36bIBIKPQ4VbAKUNId9NJMHBOgAmtgqs/3uYzZFYfXv00 +uJhHqv27iOxW4rjgpajkBvSSEtnpcgdyG6hSmK2km/PAfncqjlLk5JG/hB7F4Kgfw8W DSaw==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20230601 header.b=kVGQd3gy; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com; dara=fail header.i=@gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id 38308e7fff4ca-2f79d2c832csi842581fa.129.2024.09.13.16.19.10; Fri, 13 Sep 2024 16:19:10 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20230601 header.b=kVGQd3gy; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com; dara=fail header.i=@gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id CBFD668DF2B; Fri, 13 Sep 2024 22:22:26 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ed1-f52.google.com (mail-ed1-f52.google.com [209.85.208.52]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id E6D5568AE42 for ; Fri, 13 Sep 2024 22:22:20 +0300 (EEST) Received: by mail-ed1-f52.google.com with SMTP id 4fb4d7f45d1cf-5c40942358eso380957a12.1 for ; Fri, 13 Sep 2024 12:22:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1726255340; x=1726860140; darn=ffmpeg.org; h=subject:date:from:to:message-id:from:to:cc:subject:date:message-id :reply-to; bh=uxk720K+8Q+31Xp9+67PfHx9ldJM8Sx7M3zLNWu7Zwo=; b=kVGQd3gyOUOJKHYeVT3BTL7pLHzzJZyqM8qOc8f4L+oXD76gczLnbQF+/Pe0JyKTNJ yR3zMr3bHwCelgMuxlRPkvfoDzGOJ2v+ixptsr51Ku/owkxvUoN1E1yS8CoyQ6pxtj+o x99ojkgieaqLchdv7Sy7GAg4pLz9AO0EXdX3/YP5QvAOsYDSEYfrdZpSe25wjUHcZTrK Q/4+zopsQ8jHL43EMb3qEoddQMRXdgTd40wR9j57jRPyngMehuZBXEkNJuyJQ3SFy2kF VniOUG3v7hBlRj7C9bsnALyAKRo/em/r0R4h+5ZiEO71aRq3yV8nLwl6S7Ix3O9KPycc aYDg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1726255340; x=1726860140; h=subject:date:from:to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=uxk720K+8Q+31Xp9+67PfHx9ldJM8Sx7M3zLNWu7Zwo=; b=auF4KO3JsjhcGriE7L7YSjwkzQllNvMuq7he3opyd83gV5iLTfszHo0WW7GcXiHddP vyk9FmSJfCiYrVITm3iIb4DVhLpVlQkBTwbiOangUMs3up1YkAC9Gnfzykjr4OnN2xRM odQzZXKSiqTydpHZ1BC/ij9RJ/Ww5kS4EJZu4eHmE85/y2p3SylDGHzGb/ThD6iftaas IuPgiaK2gOTn/f3+Qw4aYZ3sPwon1m3KmCLXfzu0R6YSqSs5FrPP3s8xlHtBySaJEDMH bSWCBNdhkgGvoY0OmBYFcW30yVCn699G5dP/UwwmDTy8bhadl1gzwUxMcyDo5ja1ggIH llzw== X-Gm-Message-State: AOJu0YxQ51BjBBUbX6fKOH2S6kA9KPeM/GEynDgbSqnJzdOexnuMTtvS hH94xznmUguUox39Hgqi1HtVIQ0QkWjpj5qIDUfx1y0Imam4NeZl7w1fAA== X-Received: by 2002:a05:6402:1f0c:b0:5be:f5b0:fc38 with SMTP id 4fb4d7f45d1cf-5c4015e5da3mr19370371a12.10.1726255339417; Fri, 13 Sep 2024 12:22:19 -0700 (PDT) Received: from localhost (p200300cccf026100f587b9af6c661ff7.dip0.t-ipconnect.de. [2003:cc:cf02:6100:f587:b9af:6c66:1ff7]) by smtp.gmail.com with ESMTPSA id 4fb4d7f45d1cf-5c3ebd76eb6sm7924418a12.61.2024.09.13.12.22.18 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 13 Sep 2024 12:22:18 -0700 (PDT) Message-Id: To: From: "Marvin Scholz" Date: Sat, 18 May 2024 19:00:50 +0200 Subject: [FFmpeg-devel] [PATCH v2 1/2] doc/developer: add examples to clarify code style X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches MIME-Version: 1.0 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: ZFtp7gSVHZf3 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(-) base-commit: 6229e4ac425b4566446edefb67d5c225eb397b58 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'. +@subsection Examples +Some notable examples to illustrate common code style in FFmpeg: + +@itemize @bullet + +@item +Space around assignments and after +@code{if}/@code{do}/@code{while}/@code{for} keywords: + +@example c, good +// Good +if (condition) + av_foo(); +@end example + +@example c, good +// Good +for (size_t i = 0; i < len; i++) + av_bar(i); +@end example + +@example c, good +// Good +size_t size = 0; +@end example + +However no spaces between the parentheses and condition, unless it helps +readability of complex conditions, so the following should not be done: + +@example c, bad +// Bad style +if ( condition ) + av_foo(); +@end example + +@item +No unnecessary parentheses, unless it helps readability: + +@example c, good +// Good +int fields = ilace ? 2 : 1; +@end example + +@item +No braces around single-line blocks: + +@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; +@} +@end example + +@item +Avoid assignments in conditions where it makes sense: + +@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); +@end example + +@example c, bad +// Bad style +if (!(video_enc->chroma_intra_matrix = av_mallocz(sizeof(*video_enc->chroma_intra_matrix) * 64))) + return AVERROR(ENOMEM); +@end example + +@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); +@end example + +@item +When declaring a pointer variable, the @code{*} goes with the variable not the type: + +@example c, good +// Good +AVStream *stream; +@end example + +@example c, bad +// Bad style +AVStream* stream; +@end example + +@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}: