[phobos] Initial Phobos style guide proposal

[Steve Schveighoffer]

>________________________________
>From: Andrei Alexandrescu <andrei at erdani.com>
>
>On 03/31/2011 08:29 AM, Steve Schveighoffer wrote:
>> One thing I've noticed about std.container, and it makes it very hard
>> for me to read: Putting all ddoc comments with no indentation. In
>> particular, I have a very hard time seeing where a class or struct ends.
>> Andrei, there must be a good reason for you to do this, can you explain
>> that? I'd really prefer that the comments are put at the same
>> indentation as the code being commented.
>
>Documentation comments are meant to be multiline and treated as regular 
>text. As such, I thought it's natural that they extend from the left 
>edge as a deeply indented comment would be difficult to read (and write 
>for some).

It isn't often that ddoc comments are deeply indented.  I'd say at most 2 levels, which gives you 8 less characters out of an 80-character line.  In addition, the line breaks in the file do not dictate line breaks in the generated docs, so this is really a non-issue, the ddoc generator will reformat as necessary.


But in any case, the issue is that it messes up the indentation of the class/struct being commented.  I can't easily see where a struct begins or ends, because the text is always bringing me back to the left edge.


To me it looks as bad as this:

class A
{
void foo();
void bar();
struct Range
{
@property bool empty() const;
...
}
}

Especially if syntax highlighting isn't used (which doesn't seem to be the case for github on std.container, see https://github.com/D-Programming-Language/phobos/blob/master/std/container.d )

>
>> Also, can we standardize the comment style, at least for ddoc comments?
>> I've seen a few different styles in phobos. My favorite is:
>>
>> /**
>> * comment
>> */
>>
>> or
>>
>> /++
>> + comment
>> +/
>>
>> I do not like this:
>>
>> /**
>> comment
>> */
>>
>> because it's more difficult to distinguish commented lines from normal
>> lines.
>
>Indeed your favorite style is more difficult to maintain. Also, if a 
>parenthesized construct crosses a line, ddoc gets confused.

Another option is to have a more distinct header/footer for the comment, i.e.:

/**********************
comment
***********************/

What I find wrong with the style I disliked is that the opening/closing comment tags get lost in the noise with my visual scanning, whereas if they all line up with a common line prefix, then I can see the comment as a whole much easier.

BTW, my preferred style is really easy for me to maintain, but it's specific to my editor and key shortcuts (vim automatically adds the * prefix, and with one keystroke, I can insert needed line breaks at 80 chars along with the * prefix), so I suppose it's a valid point that maintenance can be an issue for some who don't have an editor that performs those tasks easily.

-Steve