Code Markup in Xcode

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
	  	  	  	  }
	  	  	  	  loadContent()
	  	  } 	 

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

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!