Code Markup in Xcode

Screen Shot 2016-05-28 at 12.58.13 PM

I’m working on  a fairly large Swift project. Actually no, that’s not quite true. I’m working on  a Swift project with a ViewController file that is getting disorganized and out of control. If this keeps up I might have a large project on my hands but right now it’s just a single file that is getting larger than I would like.

Apple provides some quick and dirty tools that make it easy to navigate a single file with specially formatted comments in your code. This functionality doesn’t provide automated documentation like Headerdoc. And that’s fine with me. I like how Headerdoc has become a mash up of Markdown and JavaDoc. My code is just not stable enough  for documenting  yet.

Happily Xcode’s built-in special comment parser is enough  in the early stages of development to help me  navigate a large file and remember where the  bodies are buried.

Xcode supports the following out of the box:

  • MARK: (your text here)
  • MARK: – (section divider)
  • ???: Question
  • !!!!: Warning
  • TODO: Task
  • FIXME: Bug

Xcode’s special comments  mark up the function navigation  pop-up menu so that you can find your questions, warnings, tasks, and bugs in your code without a overtaxing your the private  neural network in your skull. Unfortunately you can’t add new special comments and they don’t show up in the Symbol Navigator.

(Using the MARK: comment you can simulate adding your own special comments. MARK:  doesn’t add the  word  MARK: in front  of navigation items in the way that the other special comments do (TODO, FIXME, etc.). So you can use MARK: NOTE to navigate to notes in your Swift code if that makes you happy.)

I use the following additional special comments to keep my code organized and consistent. (Xcode will just ignore them unless I prefix each with MARK:)

  • NOTE: (when the function name is not enough)
  • HINT:  (a non-obvious reminder about a bit of code)
  • DBUG: (end of line comment marking code that probably should be removed eventually)
  • DEMO: (example usage)
	  	 	 // MARK: -
	  	  // MARK: Storyboard Actions

	  	  @IBAction func rightSwipeGesture(sender: UISwipeGestureRecognizer) {
	  	  	  	  // HINT: previous page
	  	  	  	  currentTrainIndex -= 1
	  	  	  	  if currentTrainIndex < 0 {
	  	  	  	  	  	  currentTrainIndex = trainCount - 1

	  	  @IBAction func leftSwipeGesture(sender: UISwipeGestureRecognizer) {
	  	  	  	  // HINT: next page
	  	  	  	  currentTrainIndex += 1
	  	  	  	  if currentTrainIndex == trainCount {
	  	  	  	  	  	  currentTrainIndex = 0

It would be nice if Apple allowed us to personalize  code markup  in Xcode. But only after search and ranking in the App Store are  fixed and a 1000 other higher priories are done!