> On 3 Jun 2015, at 9:03 am, Michael David Crawford <mdcrawf...@gmail.com> > wrote: > > "That's because comments are rarely maintained in sync with the actual > source code." >
So part of the responsibility of coding well is to maintain comments, not to remove them altogether. At a minimum, I comment what a method does, in broad terms, and what the parameters are for, if they’re not obvious. Also, any ”tricks” should be commented. Any code that only works because of some hidden factor that isn’t obvious should be commented. Any non-obvious algorithm should be commented, and so on. Code that is “obvious” is generally not worth commenting - it only adds clutter. The example you gave was “obvious” in my opinion, so there wouldn’t normally be a comment there, even if it was correct. All this is usually covered in the style guide for coding that your employer probably has, if they do any sort of serious coding. If you work for yourself, you should have one as well. I don’t trust completely uncommented code. —Graham _______________________________________________ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
