[PATCH] docs: point out that locals should be defined at the top of a block of code

[Pavel Hrdina]

On Thu, Jul 09, 2020 at 06:41:21PM -0400, Laine Stump wrote:
> Although we have nothing in make syntax-check to enforce this, and
> apparently there are places where it isn't the case (according to
> Dan), we should discourage the practice of defining new variables in
> the middle of a block of code.
> 
> https://www.redhat.com/archives/libvir-list/2020-July/msg00433.html
> Signed-off-by: Laine Stump <laine at redhat.com>
> ---
>  docs/coding-style.rst | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
> 
> diff --git a/docs/coding-style.rst b/docs/coding-style.rst
> index 03b89c86e5..b9b4a16987 100644
> --- a/docs/coding-style.rst
> +++ b/docs/coding-style.rst
> @@ -541,6 +541,44 @@ diligent about this, when you see a non-const pointer, you're
>  guaranteed that it is used to modify the storage it points to, or
>  it is aliased to another pointer that is.
>  
> +Defining Local Variables
> +------------------------
> +
> +Always define local variables at the top of the block in which they
> +are used (before any pure code). Although modern C compilers allow
> +defining a local variable in the middle of a block of code, this
> +practice can lead to bugs, and must be avoided in all libvirt
> +code. (As indicated in these examples, it is okay to initialize
> +variables where they are defined, even if the initialization involves
> +calling another function.)
> +
> +::
> +
> +  GOOD:
> +    int
> +    Bob(char *loblaw)

Since we are nitpicking I don't think we allow the first letter of the
function name to be uppercase. :)

Reviewed-by: Pavel Hrdina <phrdina at redhat.com>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20200710/e11a9897/attachment-0001.sig>