From 56380761359d36c6766fd3e5661ba7cdb236e8f9 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 12 Apr 2019 16:45:03 +0200 Subject: [PATCH] CODING_STYLE: export section about exporting symbols --- docs/CODING_STYLE.md | 36 +++++++++++++++++++----------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md index cad7ab2958..c8ec482def 100644 --- a/docs/CODING_STYLE.md +++ b/docs/CODING_STYLE.md @@ -68,9 +68,6 @@ title: Coding Style ## Other -- Variables and functions **must** be static, unless they have a - prototype, and are supposed to be exported. - - structs in `PascalCase` (with exceptions, such as public API structs), variables and functions in `snake_case`. @@ -113,10 +110,6 @@ title: Coding Style only jump to the end of a function, and little else. Never jump backwards! -- Public API calls (i.e. functions exported by our shared libraries) - must be marked `_public_` and need to be prefixed with `sd_`. No - other functions should be prefixed like that. - - For every function you add, think about whether it is a "logging" function or a "non-logging" function. "Logging" functions do logging on their own, "non-logging" function never log on their own and @@ -233,16 +226,6 @@ title: Coding Style global variables, for example data parsed from command lines, see below. -- When exposing public C APIs, be careful what function parameters you make - `const`. For example, a parameter taking a context object should probably not - be `const`, even if you are writing an otherwise read-only accessor function - for it. The reason is that making it `const` fixates the contract that your - call won't alter the object ever, as part of the API. However, that's often - quite a promise, given that this even prohibits object-internal caching or - lazy initialization of object variables. Moreover, it's usually not too useful - for client applications. Hence, please be careful and avoid `const` on object - parameters, unless you are very sure `const` is appropriate. - - Make sure to enforce limits on every user controllable resource. If the user can allocate resources in your code, your code must enforce some form of limits after which it will refuse operation. It's fine if it is hard-coded (at @@ -472,6 +455,25 @@ title: Coding Style - Do not print messages to stdout on error. - Do not POSIX_ME_HARDER unless necessary, i.e. avoid `+` in option string. +## Exporting Symbols + +- Variables and functions **must** be static, unless they have a prototype, and + are supposed to be exported. + +- Public API calls (i.e. functions exported by our shared libraries) + must be marked `_public_` and need to be prefixed with `sd_`. No + other functions should be prefixed like that. + +- When exposing public C APIs, be careful what function parameters you make + `const`. For example, a parameter taking a context object should probably not + be `const`, even if you are writing an otherwise read-only accessor function + for it. The reason is that making it `const` fixates the contract that your + call won't alter the object ever, as part of the API. However, that's often + quite a promise, given that this even prohibits object-internal caching or + lazy initialization of object variables. Moreover, it's usually not too + useful for client applications. Hence, please be careful and avoid `const` on + object parameters, unless you are very sure `const` is appropriate. + ## Referencing Concepts - When referring to a configuration file option in the documentation and such,