On 2011-03-31 08:00, Steve Schveighoffer wrote: > >________________________________ > >From: David Simcha <[email protected]> > >On Thu, Mar 31, 2011 at 9:29 AM, Steve Schveighoffer <[email protected]> > >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.
If you use the /++ +/ commenting style, no *'s are necessary and the issue is completely avoided, because the /++ and +/ are the only markers that the comment needs, and the editors don't go and add extra +'s or *'s. Personally, I don't understand why you'd _want_ to have all of those extra *'s. - Jonathan M Davis _______________________________________________ phobos mailing list [email protected] http://lists.puremagic.com/mailman/listinfo/phobos
