>________________________________
>From: Andrei Alexandrescu <[email protected]>
>
>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
_______________________________________________
phobos mailing list
[email protected]
http://lists.puremagic.com/mailman/listinfo/phobos
