Coding Style for local variables

Coding Style for local variables

[Morten Brørup]

The coding style guide says:

"Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."

Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of uninitialized variables.

Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?

Re: Coding Style for local variables

[Tyler Retzlaff]

On Mon, Jun 10, 2024 at 05:10:01PM +0200, Morten Brørup wrote:
> The coding style guide says:
> 
> "Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."
> 
> Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of uninitialized variables.
> 
> Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?

+1

yes please

RE: Coding Style for local variables

[Konstantin Ananyev]

> The coding style guide says:
> 
> "Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is
> const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."
> 
> Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized
> variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of
> uninitialized variables.
> 
> Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?

I know that modern C standards allow to define variable in the middle.
But I am strongly opposed to allow that in DPDK coding style.
Such practice makes code much harder to read and understand (at least for me).
Konstantin  
 

Re: Coding Style for local variables

[Ferruh Yigit]

On 6/10/2024 4:10 PM, Morten Brørup wrote:
> The coding style guide says:
> 
> "Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."
> 
> Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of uninitialized variables.
> 
> Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?
> 

My concern is it may break the consistency in the code.
If there is an existing function that defines N variables at the
beginning of the function, new feature defines a new variable close the
the feature block, this inconsistency bothers me more than all variables
being defined at top.

Variables being defined on top only bothers me when function is too big
and I can't see the variable declaration at the same time while I am
reading the code.
If functions is small enough to fit ~50% of my screen, locations doesn't
really matter, I can still observe (effectively) uninitialized variables
etc...
Instead of trying to optimize big functions, I am for doing other way
around to encourage smaller functions.
(Indeed I prefer 80 column limit with 8 space indentation for exact same
reason, this *artificial* limit only allows some number of indentation
and at some point forces developer to extract some part of code as new a
function.)

Re: Coding Style for local variables

[Stephen Hemminger]

On Tue, 11 Jun 2024 16:10:33 +0100
Ferruh Yigit <ferruh.yigit@amd.com> wrote:

> On 6/10/2024 4:10 PM, Morten Brørup wrote:
> > The coding style guide says:
> > 
> > "Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."
> > 
> > Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of uninitialized variables.
> > 
> > Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?
> >   
> 
> My concern is it may break the consistency in the code.
> If there is an existing function that defines N variables at the
> beginning of the function, new feature defines a new variable close the
> the feature block, this inconsistency bothers me more than all variables
> being defined at top.

There are few places where putting declarations in middle makes sense, like
   for (int i = 0; i < 10; i++)

> 
> Variables being defined on top only bothers me when function is too big
> and I can't see the variable declaration at the same time while I am
> reading the code.

Then the function is too big to start with!

> If functions is small enough to fit ~50% of my screen, locations doesn't
> really matter, I can still observe (effectively) uninitialized variables
> etc...
> Instead of trying to optimize big functions, I am for doing other way
> around to encourage smaller functions.

Agreed

> (Indeed I prefer 80 column limit with 8 space indentation for exact same
> reason, this *artificial* limit only allows some number of indentation
> and at some point forces developer to extract some part of code as new a
> function.)

Re: Coding Style for local variables

[Bruce Richardson]

On Mon, Jun 10, 2024 at 05:10:01PM +0200, Morten Brørup wrote:
> The coding style guide says:
> 
> "Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."
> 
> Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of uninitialized variables.
> 
> Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?
> 

+1

Declaring variables at point of first use is generally easier to read, and
makes things far simpler when commenting out blocks of code for devel or
debugging purposes - avoid those unused variable warnings.

/Bruce

Re: Coding Style for local variables

[Thomas Monjalon]

10/06/2024 18:31, Konstantin Ananyev:
> Morten said:
> > The coding style guide says:
> > 
> > "Variables should be declared at the start of a block of code rather than in the middle. The exception to this is when the variable is
> > const in which case the declaration must be at the point of first use/assignment. Declaring variable inside a for loop is OK."
> > 
> > Since DPDK switched to C11, variables can be declared where they are used, which reduces the risk of using effectively uninitialized
> > variables. "Effectively uninitialized" means initialized to 0 or NULL where declared, to silence any compiler warnings about the use of
> > uninitialized variables.
> > 
> > Can we please agree to remove the recommendation/requirement to declare variables at the start of a block of code?
> 
> I know that modern C standards allow to define variable in the middle.
> But I am strongly opposed to allow that in DPDK coding style.
> Such practice makes code much harder to read and understand (at least for me).

Yes it is convenient to know that all variables are described
in a known place, just after function parameters.

There is also a consistency concern.

Old contributors like to be in a comfort zone,
	and we don't want to lose old contributors.
New contributors may be refrained by old rules,
	and we would like to get more new contributors.

So that's a tricky decision.

RE: Coding Style for local variables

[Morten Brørup]

> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> 
> 10/06/2024 18:31, Konstantin Ananyev:
> > Morten said:
> > > The coding style guide says:
> > >
> > > "Variables should be declared at the start of a block of code rather than
> in the middle. The exception to this is when the variable is
> > > const in which case the declaration must be at the point of first
> use/assignment. Declaring variable inside a for loop is OK."
> > >
> > > Since DPDK switched to C11, variables can be declared where they are used,
> which reduces the risk of using effectively uninitialized
> > > variables. "Effectively uninitialized" means initialized to 0 or NULL
> where declared, to silence any compiler warnings about the use of
> > > uninitialized variables.
> > >
> > > Can we please agree to remove the recommendation/requirement to declare
> variables at the start of a block of code?
> >
> > I know that modern C standards allow to define variable in the middle.
> > But I am strongly opposed to allow that in DPDK coding style.
> > Such practice makes code much harder to read and understand (at least for
> me).
> 
> Yes it is convenient to know that all variables are described
> in a known place, just after function parameters.
> 
> There is also a consistency concern.
> 
> Old contributors like to be in a comfort zone,
> 	and we don't want to lose old contributors.
> New contributors may be refrained by old rules,
> 	and we would like to get more new contributors.
> 
> So that's a tricky decision.
> 

Independent research shows that readability is improved by declaring local variables as close as possible to their first use:
https://barrgroup.com/72-initialization#footnote12

Old people (like myself) need to unlearn their bad old habits (originating from limitations in old C standards), and embrace modern methods to reduce the risk of introducing bugs.

RE: Coding Style for local variables

[Konstantin Ananyev]

> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> >
> > 10/06/2024 18:31, Konstantin Ananyev:
> > > Morten said:
> > > > The coding style guide says:
> > > >
> > > > "Variables should be declared at the start of a block of code rather than
> > in the middle. The exception to this is when the variable is
> > > > const in which case the declaration must be at the point of first
> > use/assignment. Declaring variable inside a for loop is OK."
> > > >
> > > > Since DPDK switched to C11, variables can be declared where they are used,
> > which reduces the risk of using effectively uninitialized
> > > > variables. "Effectively uninitialized" means initialized to 0 or NULL
> > where declared, to silence any compiler warnings about the use of
> > > > uninitialized variables.
> > > >
> > > > Can we please agree to remove the recommendation/requirement to declare
> > variables at the start of a block of code?
> > >
> > > I know that modern C standards allow to define variable in the middle.
> > > But I am strongly opposed to allow that in DPDK coding style.
> > > Such practice makes code much harder to read and understand (at least for
> > me).
> >
> > Yes it is convenient to know that all variables are described
> > in a known place, just after function parameters.
> >
> > There is also a consistency concern.
> >
> > Old contributors like to be in a comfort zone,
> > 	and we don't want to lose old contributors.
> > New contributors may be refrained by old rules,
> > 	and we would like to get more new contributors.
> >
> > So that's a tricky decision.
> >
> 
> Independent research shows that readability is improved by declaring local variables as close as possible to their first use:
> https://barrgroup.com/72-initialization#footnote12

Hmm... seems  they don't provide any data to back up their statements.
Specially that one sounds weird for me:
" Too many programmers assume the C run-time will watch out for them, e.g., by zeroing the value of uninitialized variables on system startup."
Why on earth people would assume that?
And what exactly means 'too many? 1%? 10%? 90%? 

> 
> Old people (like myself) need to unlearn their bad old habits (originating from limitations in old C standards), and embrace modern
> methods to reduce the risk of introducing bugs.

Allowing to define variables in the middle of the code by itself wouldn't prevent of use of un-initialized variables.
From other side - compilers are quite good these days to catch such bugs.
So I don't think it is a completing argument..    
 

RE: Coding Style for local variables

[Morten Brørup]

> From: Konstantin Ananyev [mailto:konstantin.ananyev@huawei.com]
> 
> > > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > >
> > > 10/06/2024 18:31, Konstantin Ananyev:
> > > > Morten said:
> > > > > The coding style guide says:
> > > > >
> > > > > "Variables should be declared at the start of a block of code rather
> than
> > > in the middle. The exception to this is when the variable is
> > > > > const in which case the declaration must be at the point of first
> > > use/assignment. Declaring variable inside a for loop is OK."
> > > > >
> > > > > Since DPDK switched to C11, variables can be declared where they are
> used,
> > > which reduces the risk of using effectively uninitialized
> > > > > variables. "Effectively uninitialized" means initialized to 0 or NULL
> > > where declared, to silence any compiler warnings about the use of
> > > > > uninitialized variables.
> > > > >
> > > > > Can we please agree to remove the recommendation/requirement to
> declare
> > > variables at the start of a block of code?
> > > >
> > > > I know that modern C standards allow to define variable in the middle.
> > > > But I am strongly opposed to allow that in DPDK coding style.
> > > > Such practice makes code much harder to read and understand (at least
> for
> > > me).
> > >
> > > Yes it is convenient to know that all variables are described
> > > in a known place, just after function parameters.
> > >
> > > There is also a consistency concern.
> > >
> > > Old contributors like to be in a comfort zone,
> > > 	and we don't want to lose old contributors.
> > > New contributors may be refrained by old rules,
> > > 	and we would like to get more new contributors.
> > >
> > > So that's a tricky decision.
> > >
> >
> > Independent research shows that readability is improved by declaring local
> variables as close as possible to their first use:
> > https://barrgroup.com/72-initialization#footnote12

The footnote refers to [Uwano], which can be found here:
[Uwano]: https://www.cs.kent.edu/~jmaletic/Prog-Comp/Papers/Uwano06.pdf

> 
> Hmm... seems  they don't provide any data to back up their statements.
> Specially that one sounds weird for me:
> " Too many programmers assume the C run-time will watch out for them, e.g., by
> zeroing the value of uninitialized variables on system startup."
> Why on earth people would assume that?

Not all programmers remember all the rules all the time. Especially junior developers.

> And what exactly means 'too many? 1%? 10%? 90%?

I guess that "too many" means that it is a statistically significant cause of bugs.

PS:
I like your way of reasoning.
I guess the Barr Group is trying to keep it short in their handbook, omitting the details from the underlying research.
It's a shame Jack Ganssle stopped giving his "How to Develop Better Firmware Faster" seminar (https://www.ganssle.com/classes.htm). All his "rule-of-thumb" guidelines are backed with hard data from references and experiments!

> 
> >
> > Old people (like myself) need to unlearn their bad old habits (originating
> from limitations in old C standards), and embrace modern
> > methods to reduce the risk of introducing bugs.
> 
> Allowing to define variables in the middle of the code by itself wouldn't
> prevent of use of un-initialized variables.
> From other side - compilers are quite good these days to catch such bugs.
> So I don't think it is a completing argument..

Please note that I am talking about "effectively uninitialized" variables,
meaning variables that have been initialized with dummy values like NULL, 0 or -1,
only to make the "use of uninitialized variable" compiler warnings go away.

Initializing variables with dummy values effectively disables the compiler's ability to catch bugs where a variable is being used before it has been assigned a (correct) value, because the compiler cannot know that the variable has been initialized with a dummy value.

The advantages of declaring the variable where it is used the first time are:
- The developer is much likelier to assign it the correct value to begin with.
- The reviewer is much likelier to spot if it is initialized with an incorrect value.

Re: Coding Style for local variables

[Stephen Hemminger]

On Thu, 20 Jun 2024 11:02:21 +0200
Morten Brørup <mb@smartsharesystems.com> wrote:

> > From: Konstantin Ananyev [mailto:konstantin.ananyev@huawei.com]
> >   
> > > > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > > >
> > > > 10/06/2024 18:31, Konstantin Ananyev:  
> > > > > Morten said:  
> > > > > > The coding style guide says:
> > > > > >
> > > > > > "Variables should be declared at the start of a block of code rather  
> > than  
> > > > in the middle. The exception to this is when the variable is  
> > > > > > const in which case the declaration must be at the point of first  
> > > > use/assignment. Declaring variable inside a for loop is OK."  
> > > > > >
> > > > > > Since DPDK switched to C11, variables can be declared where they are  
> > used,  
> > > > which reduces the risk of using effectively uninitialized  
> > > > > > variables. "Effectively uninitialized" means initialized to 0 or NULL  
> > > > where declared, to silence any compiler warnings about the use of  
> > > > > > uninitialized variables.
> > > > > >
> > > > > > Can we please agree to remove the recommendation/requirement to  
> > declare  
> > > > variables at the start of a block of code?  
> > > > >
> > > > > I know that modern C standards allow to define variable in the middle.
> > > > > But I am strongly opposed to allow that in DPDK coding style.
> > > > > Such practice makes code much harder to read and understand (at least  
> > for  
> > > > me).
> > > >
> > > > Yes it is convenient to know that all variables are described
> > > > in a known place, just after function parameters.
> > > >
> > > > There is also a consistency concern.
> > > >
> > > > Old contributors like to be in a comfort zone,
> > > > 	and we don't want to lose old contributors.
> > > > New contributors may be refrained by old rules,
> > > > 	and we would like to get more new contributors.
> > > >
> > > > So that's a tricky decision.

Either way looks ok to me. See no need for hard and fast rules in this area.
But please no patches to change existing code.