From patchwork Thu Nov 17 10:09:42 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Khirnov X-Patchwork-Id: 39310 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a21:999a:b0:a4:2148:650a with SMTP id ve26csp994216pzb; Thu, 17 Nov 2022 02:11:02 -0800 (PST) X-Google-Smtp-Source: AA0mqf5ZGEGWBzvNXy9/kVuQMqJmkqfEe64JrSAMjfNRzMgzF06/Z+9vPlJNhNO1mwiLHofQap7h X-Received: by 2002:a17:906:1b52:b0:7ad:90dc:b7d4 with SMTP id p18-20020a1709061b5200b007ad90dcb7d4mr1528401ejg.278.1668679861986; Thu, 17 Nov 2022 02:11:01 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1668679861; cv=none; d=google.com; s=arc-20160816; b=kQkBpmMXxupDTS8o4PPkcXIsqD1cKUx6MN0HHtj48Lbg1lu7NOrwX7Rt5E+c+4wSOQ 5Umgs7PgLU2pIcZ2MhkDbO8MK3TDJHXcuwEnzQpInclrw+k3HzdpOSPqsDEEZ2lwbslT iZ98Bs9XYKmu04tO6uA8fwgsM0yFOQ2KnxHDu2cVZvbhiOu489AvowmFMywk7/8REvpH NAzsLK13eGsixA2xaCfLoycidqyVyGEyD7YzvQcO2BjgGpwwZA9Wf4KcFvlf8n5jU0XO y2P6bSUgYD1Y9bo6YB6QnqzetYhV1i0Nydm8d93xvaeYJI0CgoBci2Uyxlx/9vVdIZo8 H2Rw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:reply-to:list-subscribe :list-help:list-post:list-archive:list-unsubscribe:list-id :precedence:subject:mime-version:references:in-reply-to:message-id :date:to:from:delivered-to; bh=t3F25Aeu4Khhsv/lDWJj0P4Zu+SQLcFD78dBuyMqyEE=; b=yuG0mB2wAZ66aHAiktBYzhNL2wv92VOqCB0BtAsEq5w3klKAK0yill7irsonhn5tHJ NPPL6JJXPrhU7ZPXDAqKMVBejXLaJG3qdGAVDBVQAnatmpOha9Zj+JKgZpp6G3GB156U PXw65ylOzTujZ5+qCUkCHrw6yYjUkwVXDQbJ7PklZpvSE90h9ugHskEMrGY64YE0EWGx Pc34poYRS9rSnjKQs/DR7aHQdJe7qTYv0Hwgn/ueKPpIOh9Q1APQEo+WeIVRsqy8oVRE MJKMYKLWYYgaFDQNFP7PcDcWC4HcQg3PvMSnSR6W+C/FUx5pSXeiZEQQc4im1b3uqDJp Dy3Q== ARC-Authentication-Results: i=1; mx.google.com; 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 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id hc6-20020a170907168600b007addf59b7f5si229570ejc.794.2022.11.17.02.11.01; Thu, 17 Nov 2022 02:11:01 -0800 (PST) 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; 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 Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 7BDEE68BD36; Thu, 17 Nov 2022 12:10:10 +0200 (EET) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail0.khirnov.net (red.khirnov.net [176.97.15.12]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id CABDA68BCFF for ; Thu, 17 Nov 2022 12:10:02 +0200 (EET) Received: from localhost (localhost [IPv6:::1]) by mail0.khirnov.net (Postfix) with ESMTP id 9E0F62405EC for ; Thu, 17 Nov 2022 11:09:59 +0100 (CET) Received: from mail0.khirnov.net ([IPv6:::1]) by localhost (mail0.khirnov.net [IPv6:::1]) (amavisd-new, port 10024) with ESMTP id 7nHQ3t9OnnsT for ; Thu, 17 Nov 2022 11:09:58 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:2a00:c500:561:201::7]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "libav.khirnov.net", Issuer "smtp.khirnov.net SMTP CA" (verified OK)) by mail0.khirnov.net (Postfix) with ESMTPS id B17282405F9 for ; Thu, 17 Nov 2022 11:09:56 +0100 (CET) Received: from libav.khirnov.net (libav.khirnov.net [IPv6:::1]) by libav.khirnov.net (Postfix) with ESMTP id 4B2E93A0656 for ; Thu, 17 Nov 2022 11:09:50 +0100 (CET) From: Anton Khirnov To: ffmpeg-devel@ffmpeg.org Date: Thu, 17 Nov 2022 11:09:42 +0100 Message-Id: <20221117100942.6217-7-anton@khirnov.net> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20221117100942.6217-1-anton@khirnov.net> References: <20221117100942.6217-1-anton@khirnov.net> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH 7/7] doc/developer.texi: extend and update naming conventions 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 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: P3b+/N/Q1czY Bring it up to date with current practice, as the current text does not cover everything. Drop the reference to unprefixed exported symbols, which do not exist anymore. --- doc/developer.texi | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/doc/developer.texi b/doc/developer.texi index a2719e7518..48c27f3005 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -191,39 +191,50 @@ int myfunc(int my_parameter) @end example @section Naming conventions -All names should be composed with underscores (_), not CamelCase. For example, -@samp{avfilter_get_video_buffer} is an acceptable function name and -@samp{AVFilterGetVideo} is not. The exception from this are type names, like -for example structs and enums; they should always be in CamelCase. -There are the following conventions for naming variables and functions: +Names of functions, variables, and struct members must be lowercase, using +underscores (_) to separate words. For example, @samp{avfilter_get_video_buffer} +is an acceptable function name and @samp{AVFilterGetVideo} is not. -@itemize @bullet -@item -For local variables no prefix is required. +Struct, union, enum, and typedeffed type names must use CamelCase. All structs +and unions should be typedeffed to the same name as the struct/union tag, e.g. +@code{typedef struct AVFoo @{ ... @} AVFoo;}. Enums are typically not +typedeffed. +Enumeration constants and macros must be UPPERCASE, except for macros +masquerading as functions, which should use the function naming convention. + +All identifiers in the libraries should be namespaced as follows: +@itemize @bullet @item -For file-scope variables and functions declared as @code{static}, no prefix -is required. +No namespacing for identifiers with file and lower scope (e.g. local variables, +static functions), and struct and union members, @item -For variables and functions visible outside of file scope, but only used -internally by a library, an @code{ff_} prefix should be used, -e.g. @samp{ff_w64_demuxer}. +The @code{ff_} prefix must be used for variables and functions visible outside +of file scope, but only used internally within a single library, e.g. +@samp{ff_w64_demuxer}. This prevents name collisions when FFmpeg is statically +linked. @item For variables and functions visible outside of file scope, used internally across multiple libraries, use @code{avpriv_} as prefix, for example, @samp{avpriv_report_missing_feature}. +@item +All other internal identifiers, like private type or macro names, should be +namespaced only to avoid possible internal conflicts. E.g. @code{H264_NAL_SPS} +vs. @code{HEVC_NAL_SPS}. + @item Each library has its own prefix for public symbols, in addition to the commonly used @code{av_} (@code{avformat_} for libavformat, @code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc). Check the existing code and choose names accordingly. -Note that some symbols without these prefixes are also exported for -retro-compatibility reasons. These exceptions are declared in the -@code{lib/lib.v} files. + +@item +Other public identifiers (struct, union, enum, macro, type names) must use their +library's public prefix (@code{AV}, @code{Sws}, or @code{Swr}). @end itemize Furthermore, name space reserved for the system should not be invaded.