Question

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 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.

/* 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.

Answer 1

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