I rarely use comments when I’m coding1. I do make one exception though; using
// TODO: and
// FIXME: to highlight pieces of code I need to revisit at a later date. The advantage of doing this is that the lines then show up in the jump bar popover in bold text with one-click access to the exact line:
The issue I have with this is that it is very easy to forget about them unless you are using the jump bar frequently. I used to log them in my todo manager, Things, but that duplicates the workload. It would be much more useful if those errors were flagged in some way…
Jeffrey Sambells wrote a post on how to flag these comments as Xcode warnings but that only applies for Objective-C. With a slight tweak, here is a run script build phase for flagging
FIXME: as warnings in a Swift project:
The result is an unmissable warning whenever you run your project.
I don’t know about you, but I feel more compelled to clean up these yellow warnings than ticking things off in a todo list.
Swift 4.2 Update (18th September 2018)
It is now possble with Swift 4.2 to do something similar to the above without the need for a script build phase:
#error() you can now generate warnings and errors in code without the need for comments or a build phase. You may prefer to use comments still in which case the above still works with iOS 12 / Xcode 10 but this language-level support may be more beneficial in some situations.
If your code needs commenting, it isn’t clear enough. Refactor until it is. If it doesn’t make sense because of semantics, rethink your naming conventions. ↩︎