[llvm-commits] [llvm] r76723 - /llvm/trunk/docs/CodingStandards.html

[Chris Lattner]

On Jul 22, 2009, at 9:35 AM, Daniel Dunbar wrote:
>> +<p>
>> +In general, we strive to reduce indentation where ever possible.   
>> This is useful
>> +because we want code to <a href="#scf_codewidth">fit into 80  
>> columns</a> without
>> +wrapping horribly, but also because it makes it easier to  
>> understand the code.
>> +Namespaces are a funny thing: they are often large, and we often  
>> desire to put
>> +lots of stuff into them (so they can be large).  Other times they  
>> are tiny,
>> +because they just hold an enum or something similar.  In order to  
>> balance this,
>> +we use different approaches for small versus large namespaces.
>> +</p>
>
> I medium-strongly dislike this choice of style. :)
>
> A personal "guideline" for style guidelines is that they should be
> nearly automatic; a guideline that is easier to apply is more likely
> to be followed consistently, and in then end I prefer consistency over
> any particular style choice.

Ok, sure.  OTOH there is a lot of wiggle room intended.

> This guideline is hard to follow because when writing a class you
> can't normally predict its size; so you don't know the indentation.
> Similarly, in practice this guideline will end up being frequently not
> followed, as code changes and whether it fits "on screen" changes.
> Your editor is also not particularly going to help you apply it.

The idea is that it should only be used for obviously small concepts,  
things like a functor for sorting would be a good candidate, anything  
that is non-trivial should use the 'long' style.

> If the strongest motivation is reduce indentation, then I see little
> value in making the distinction, we could just never indent
> namespaces. I think the "small" case only applies in a few scenarios,
> and indenting them adds little value.

I agree that it may not be worth mentioning.  I don't have a strong  
opinion.

>> +<p>Because the class is large, we don't expect that the reader can  
>> easily
>> +understand the entire concept in a glance, and the end of the file  
>> (where the
>> +namespaces end) may be a long ways away from the place they open.   
>> As such,
>> +indenting the contents of the namespace doesn't add any value, and  
>> detracts from
>> +the readability of the class.  In these cases it is best to  
>> <em>not</em> indent
>> +the contents of the namespace.</p>
>
> I think this argument is specious -- both because I've never felt
> indenting a namespace hurt readability (although I agree this could
> happen if we used many levels of namespaces since it would collide
> with the 80-column rule), and because one is generally aware of the
> enclosing indentation layer by virtue of the indentation of method
> names, etc.
>
> Put another way, we always indent in class definitions, and it doesn't
> hurt readability.

Indenting large units of code really does hurt readability IMO.  It  
causes lines to get wrapped and adds conceptual complexity.  By not  
indenting the namespace, it is saying that it is an organizational  
concept.  If I understand you correctly, you prefer to always indent  
all namespaces?

-Chris