[phobos] Initial Phobos style guide proposal

[Steve Schveighoffer]

>________________________________
>From: David Simcha <dsimcha at gmail.com>
>On Thu, Mar 31, 2011 at 9:29 AM, Steve Schveighoffer <schveiguy at yahoo.com> 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.
>>
>>
>>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
>>*/
>>
>I've switched the other way recently.  The problem with your example is that it's a huge pain when you go to modify the comment and need to keep all those extra *'s in sync.  Furthermore, if you're using an editor with syntax highlighting, I don't find distinguishing comments and code to be even the slightest bit of a problem.


Keeping the *'s in sync has become second nature to me.  Plus my editor makes this easy.  In vim, I use 'J' to join a line to the next one, then 'dw' to delete the *.  Finally, I have 'K' mapped to 'gql', which in one keystroke, inserts all necessary line breaks for the paragraph (for 80 chars) and automatically indents and inserts '*' prefixes.

So I have been somewhat insulated from most of that pain.  But I see your point if you don't have those shortcuts.

As far as syntax highlighting, github doesn't do that in some cases (including std.container), so comments aren't easily distinguished.

The real issue I have with the style is that the /* and */ are hard to visually see next to the comment and surrounding code.  I think if they were simply more distinct than the rest of the comment then it would help.

For example, these two styles would also work for me:

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

or

/**
   comment

*/

-Steve