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

[Daniel Dunbar]

On Wed, Jul 22, 2009 at 11:24 AM, Chris Lattner<clattner at apple.com> wrote:
> On Jul 22, 2009, at 9:35 AM, Daniel Dunbar wrote:
>> 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.

Ok, that makes sense to me, since those use cases are more write-once.

>> 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?

I would prefer either (A) never indent namespaces, or (B) always
indent namespaces, with a guideline that (non-trivial) function bodies
should not be implemented inside the namespace.

Of the two, I slightly prefer the latter, because:
1. It encourages moving the function body out of a class definition,
which increases readability (IMO). And hey, you get two extra spaces
to avoid wrapping! The downside is you have to replicate the
definition.

2. I slightly prefer the look of an indented namespace.

3. It works OOTB on emacs. :)

The key point of both these options is that it is always obvious
whether code is matching the guidelines and obvious how to fix.
However, if the "short" cases is limited to the "obvious" cases, like
a single enum or a single small class then I agree this isn't a big
deal -- although it still has the downside that I can't (easily) make
my editor do the right thing automatically.

 - Daniel