Commenting Well

Traditional comments have gone out of fashion in some circles. Comments aren’t compiled or executed. They don’t naturally change and evolve along with the code they decorate. Because of this, some coders have stepped back from their use or they hesitate to incorporate what might be a frivolous use, believing less is more.

To get a sense of this philosophy, developer Andrew Warner writes in his “Beware the Siren Song of Comments” blog post[80] that comments are naturally subject to decay. Warner cites Robert C. Martin, writing in Clean Code (Prentice Hall, 2009[81]), that comments are always a failure on the part of the coder. The quote he uses suggests that comments compensate for a coder’s failure to express specific intent ...

Get Swift Style, 1st Edition now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.