XCode 4 comment formatting (line wrapping)

It's my opinion that multi-line comments should ideally appear something like this:

/* this is a mult-line comment, which wraps lines at some reasonable length,
 * usually approximately 80 characters. this way, comments are easy to read
 * and, with any half way 开发者_如何学JAVAcapable text editor, easy to edit without having
 * to manually reshuffle lines, line breaks, and the comment leader. */

// this is a mult-line comment, which wraps lines at some reasonable length,
// usually approximately 80 characters. this way, comments are easy to read
// and, with any half way capable text editor, easy to edit without having
// to manually reshuffle lines, line breaks, and the comment leader.

/* this is a mult-line comment, which wraps lines at some reasonable length,
   usually approximately 80 characters. this way, comments are easy to read
   and, with any half way capable text editor, easy to edit without having
   to manually reshuffle lines, line breaks, and the comment leader. */

However, XCode has no support for managing comments in this style. You must manually hit return at the right time to wrap comments at a decent width, and then editing them becomes a complete PITA.

Or, you just never hit return and let the editor wrap it at the edge of your editor screen. But if you're like me, your editor is much wider than the ideal word wrapping line length.

Moreover, XCode taunts me by offering a feature to render a wrapping guide at 80 characters in the editor, yet this is purely a visual feature with no mechanics to back it up. This feels like handing a garden shovel to someone used to using a backhoe.

Do I need a reality check here - am I thinking the wrong way - or is XCode extremely lacking in basic paragraph-style comment formatting?

What do seasoned, responsible, professional Objective-C developers do when making substantial comments in their code? Help me see the light here.

Note: for XCode 3, I wrote a hand-rolled script which reformatted text and bound it to a hot key. I haven't figured out how to do this in XCode 4 yet. But how to script XCode 4 is a bit orthogonal to the issue: it smells bad to have to augment an IDE with such basics, my question is about the style and culture expectations of XCode developers.

Thanks for your advice.

I agree it should be built-in to Xcode. But anyway, here's how to add it to Xcode4 quickly by creating an service item that calls a script and assigning it a keyboard shortcut:

1. Open Automator. Create a service.
2. Set the service to let the output replace the selected text, and to receive selected text in the copy of Xcode you choose.
3. Drag in the "Run Shell Script" action as the only action in your service.
4. Replace the default shell script "cat" with "fmt -n -s -p -w80". This calls the fmt utility to reformat your text, allowing lines to begin with a period, collapsing whitespace within lines, allowing indented paragraphs, wrapping lines at 80 character columns. Check the man page for fmt for other options. Obviously, you can go nuts here by piping the text through emacs or markdown or whatever.
5. Save the service with a sensible name like "Reformat-to-80"

Now, when you have text selected in Xcode, you will be able to reformat it to 80 characters by selecting the service via the menu bar: Xcode / Services / Reformat-to-80.

Now let's assign a keyboard shortcut to it:

1. Open the Keyboard Preference Pane, go to the Keyboard Shortcuts tab.
2. Select Application Shortcuts in the left pane.
3. In the right pane, using the add button (the +) to add a new shortcut for the copy of Xcode you selected earlier. Type in the exact name you used for the service and add a keyboard shortcut of your choice.

Now, in Xcode, you can use that keyboard shortcut to replace the selected text with the output of the shell script, which will reformat the text to

Obviously, you can go nuts here by piping the text through emacs

After many years of expecting Emacs's advanced idiosyncrasies when reflowing comments, I did. Assuming you can get over the grossness of Xcode calling out to Emacs for scripting, save the following script as fill-region (or something similar) and make it executable.

#!/usr/bin/env emacs --script
(with-temp-buffer
  ;; Would like to implement --help but Emacs eats that before I can
  ;; process it here.
  (let ((param (nth 0 command-line-args-left)))
    (if param (funcall (intern param))))

  (condition-case nil
      (while t
        (insert (read-from-minibuffer ""))
        (insert "\n"))
    (error nil))
  (fill-region (point-min) (point-max))
  (princ (buffer-string)))

Then create an Automator service that executes this script with the appropriate language argument (e.g. fill-region c++-mode for C/C++/Objective-C) and replaces the selected text.

Even if you don't use Emacs, this is a drop-in replacement for the use of fmt above that's considerably better at comment formatting.

Adding to user797758's answer: To customize the column at which his emacs's script wraps your text, add a set-fill-column call before the fill-region call. For example, the below script will wrap at 100 characters.

#!/usr/bin/env emacs --script
(with-temp-buffer
  (let ((param (nth 0 command-line-args-left)))
    (if param (funcall (intern param))))

  (condition-case nil
      (while t
        (insert (read-from-minibuffer ""))
        (insert "\n"))
    (error nil))
  (set-fill-column 100)
  (fill-region (point-min) (point-max))
  (princ (buffer-string)))

Well it has never been a big deal to me how things are formatted, (personally, and I never have large amounts of text commented) but here is something I think you will find to be very useful. To Comment Out a Block of Code, you can quickly comment out a block of code as follows:

Select one or more lines of code to comment
    Command-/