spacing suggestion for new code

[Martin Sebor <se...@roguewave.com>]

While reviewing all the new code that's been added I'm finding it
difficult to spot where one namespace-scope definition ends and
another starts because the spacing between them (the number of
newlines) is the same as the spacing between members, namely 1
blank line. I find code easier to read when namespace scope
definitions of functions and classes that span more than one
line are separated by two blank lines.

Existing code likely isn't completely consistent in this regard,
and I'm sure examples of both styles could be found, but I'd like
to think the two-line style is prevalent. Either way, in the
interest of readability, I'd like to suggest that we adopt the
two-line spacing style for all new code. Yes?

Martin

Re: spacing suggestion for new code

[Martin Sebor <se...@roguewave.com>]

Travis Vitek wrote:
> Martin Sebor wrote:
>  
>> Eric Lemings wrote:
>>>  
>>>
>>>> -----Original Message-----
>>>> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
>>>> Sent: Thursday, June 26, 2008 5:21 PM
>>>> To: dev@stdcxx.apache.org
>>>> Subject: spacing suggestion for new code
>>>>
>>>> While reviewing all the new code that's been added I'm finding it
>>>> difficult to spot where one namespace-scope definition ends and
>>>> another starts because the spacing between them (the number of
>>>> newlines) is the same as the spacing between members, namely 1
>>>> blank line. I find code easier to read when namespace scope
>>>> definitions of functions and classes that span more than one
>>>> line are separated by two blank lines.
>>>>
>>>> Existing code likely isn't completely consistent in this regard,
>>>> and I'm sure examples of both styles could be found, but I'd like
>>>> to think the two-line style is prevalent. Either way, in the
>>>> interest of readability, I'd like to suggest that we adopt the
>>>> two-line spacing style for all new code. Yes?
>>> That's my general preference as well.  I prefer to use two lines to
>>> separate unrelated logical groups.  If the groups are related, I'll use
>>> 1 line to separate them.  Within a logical group, I do not use any blank
>>> lines.
>> Your rule sounds a bit more complex than what I'm suggesting.
>> Determining what logically belongs together requires an
>> understanding of the definitions. What I'm looking for is
>> a purely visual clue to help me tell one namespace-scope
>> declarative region (mostly just class or function definition)
>>from another.
> 
> Should either scheme apply to linkage specifiers?

You mean extern "C" or "C++" blocks? I think so. Syntactically,
there's little difference between them and namespaces.

> 
> Personally, I like the flexibility to use zero lines in some places...
> 
>   // i prefer this...
> 
>   _RWSTD_NAMESPACE(__rw) {

...and clearly also zero spaces before the open paren ;-)

>       struct __rw_whatever_type;
>   } // namespace __rw
> 
>   // as opposed to this...
> 
>   _RWSTD_NAMESPACE(__rw) {
> 
> 
>       struct __rw_whatever_type;
> 
> 
>   } // namespace __rw

Now this would be just plain silly! ;-)

The point of my suggestion is to help with the readability
of adjacent definitions that span several lines of code.
It seems obvious that the two blank lines don't make the
code any easier to read than one. If __rw_whatever_type
were a definition of the type spanning several lines,
that would be a different story.

That said, I find the style you show above a bit too
compact. I'd hope for a pair of blank lines around the
declaration of the struct, even with a comment above
the declaration.

Martin

> 
> As long as the number of lines of whitespace doesn't outnumber the number of lines of 'code', I'm fine with using multiple lines of whitspace. Other than that, I don't really have a preference.
> 
> Travis

RE: spacing suggestion for new code

[Eric Lemings <Er...@roguewave.com>]

 

> -----Original Message-----
> From: Travis Vitek [mailto:Travis.Vitek@roguewave.com] 
> Sent: Friday, June 27, 2008 10:16 AM
> To: dev@stdcxx.apache.org
> Subject: RE: spacing suggestion for new code
> 
> 
...
> 
> As long as the number of lines of whitespace doesn't 
> outnumber the number of lines of 'code', I'm fine with using 
> multiple lines of whitspace. Other than that, I don't really 
> have a preference.

I think that's an acceptable exception: the number of blanks lines don't
exceed the number of lines with code.

Brad.

RE: spacing suggestion for new code

[Travis Vitek <Tr...@roguewave.com>]

Martin Sebor wrote:
 
>Eric Lemings wrote:
>>  
>> 
>>> -----Original Message-----
>>> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
>>> Sent: Thursday, June 26, 2008 5:21 PM
>>> To: dev@stdcxx.apache.org
>>> Subject: spacing suggestion for new code
>>>
>>> While reviewing all the new code that's been added I'm finding it
>>> difficult to spot where one namespace-scope definition ends and
>>> another starts because the spacing between them (the number of
>>> newlines) is the same as the spacing between members, namely 1
>>> blank line. I find code easier to read when namespace scope
>>> definitions of functions and classes that span more than one
>>> line are separated by two blank lines.
>>>
>>> Existing code likely isn't completely consistent in this regard,
>>> and I'm sure examples of both styles could be found, but I'd like
>>> to think the two-line style is prevalent. Either way, in the
>>> interest of readability, I'd like to suggest that we adopt the
>>> two-line spacing style for all new code. Yes?
>> 
>> That's my general preference as well.  I prefer to use two lines to
>> separate unrelated logical groups.  If the groups are related, I'll use
>> 1 line to separate them.  Within a logical group, I do not use any blank
>> lines.
>
>Your rule sounds a bit more complex than what I'm suggesting.
>Determining what logically belongs together requires an
>understanding of the definitions. What I'm looking for is
>a purely visual clue to help me tell one namespace-scope
>declarative region (mostly just class or function definition)
>from another.
>

Should either scheme apply to linkage specifiers?

Personally, I like the flexibility to use zero lines in some places...

  // i prefer this...

  _RWSTD_NAMESPACE(__rw) {
      struct __rw_whatever_type;
  } // namespace __rw

  // as opposed to this...

  _RWSTD_NAMESPACE(__rw) {


      struct __rw_whatever_type;


  } // namespace __rw

As long as the number of lines of whitespace doesn't outnumber the number of lines of 'code', I'm fine with using multiple lines of whitspace. Other than that, I don't really have a preference.

Travis

Re: spacing suggestion for new code

[Martin Sebor <se...@roguewave.com>]

Eric Lemings wrote:
>  
> 
>> -----Original Message-----
>> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
>> Sent: Thursday, June 26, 2008 5:21 PM
>> To: dev@stdcxx.apache.org
>> Subject: spacing suggestion for new code
>>
>> While reviewing all the new code that's been added I'm finding it
>> difficult to spot where one namespace-scope definition ends and
>> another starts because the spacing between them (the number of
>> newlines) is the same as the spacing between members, namely 1
>> blank line. I find code easier to read when namespace scope
>> definitions of functions and classes that span more than one
>> line are separated by two blank lines.
>>
>> Existing code likely isn't completely consistent in this regard,
>> and I'm sure examples of both styles could be found, but I'd like
>> to think the two-line style is prevalent. Either way, in the
>> interest of readability, I'd like to suggest that we adopt the
>> two-line spacing style for all new code. Yes?
> 
> That's my general preference as well.  I prefer to use two lines to
> separate unrelated logical groups.  If the groups are related, I'll use
> 1 line to separate them.  Within a logical group, I do not use any blank
> lines.

Your rule sounds a bit more complex than what I'm suggesting.
Determining what logically belongs together requires an
understanding of the definitions. What I'm looking for is
a purely visual clue to help me tell one namespace-scope
declarative region (mostly just class or function definition)
from another.

Martin

> 
> In the case of namespaces, I'd use 2 blank lines to separate the
> namespace from its non-namespace members though I would use only 1 blank
> line to separate the namespace from nested namespaces.
> 
> 	namespace A {
> 
> 	namespace B {
> 
> 
> 	class T;
> 
> 
> 	} // namespace B
> 
> 
> 	enum { E = 1 };
> 
> 
> 	} // namespace A
> 
> Brad.

RE: spacing suggestion for new code

[Eric Lemings <Er...@roguewave.com>]

 

> -----Original Message-----
> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
> Sent: Thursday, June 26, 2008 5:21 PM
> To: dev@stdcxx.apache.org
> Subject: spacing suggestion for new code
> 
> While reviewing all the new code that's been added I'm finding it
> difficult to spot where one namespace-scope definition ends and
> another starts because the spacing between them (the number of
> newlines) is the same as the spacing between members, namely 1
> blank line. I find code easier to read when namespace scope
> definitions of functions and classes that span more than one
> line are separated by two blank lines.
> 
> Existing code likely isn't completely consistent in this regard,
> and I'm sure examples of both styles could be found, but I'd like
> to think the two-line style is prevalent. Either way, in the
> interest of readability, I'd like to suggest that we adopt the
> two-line spacing style for all new code. Yes?

That's my general preference as well.  I prefer to use two lines to
separate unrelated logical groups.  If the groups are related, I'll use
1 line to separate them.  Within a logical group, I do not use any blank
lines.

In the case of namespaces, I'd use 2 blank lines to separate the
namespace from its non-namespace members though I would use only 1 blank
line to separate the namespace from nested namespaces.

	namespace A {

	namespace B {


	class T;


	} // namespace B


	enum { E = 1 };


	} // namespace A

Brad.