I once worked for a company that had quite meticulous style rules regarding comments. I was also required to use a specific text editor because someone had written scripts that either enabled or enforced the comment style rules.
I resigned in protest because their actual source code is quite likely to get someone killed someday, quite likely a great many people. They do industrial control systems software. Consider that the Stuxnet and Flame worms attacked HMI/SCADA software. I do comment tricky stuff. While I don't write actual comments regarding input parameters or return results, I do assert them - "assert( ptr != NULL )". I regard assertions as documentation not just tests; if you intentionally change the input parameter space, then your assertions will fail. Given that you really did want to change the parameters, you'll be forced to update the assertions as well. That's better than trying to keep comments in sync as there is no really satisfying test for correct comments. I quite commonly ask potential employers whether they have any kind of coding conventions. Whether I pursue the job has a lot to do with what those conventions actually are. If they're picky about their comments I withdraw my application. If their coding conventions are the sort that are likely to lead to correct code then I pursue the job with enthusiasm. Michael David Crawford, Consulting Software Engineer mdcrawf...@gmail.com http://www.warplife.com/mdc/ Available for Software Development in the Portland, Oregon Metropolitan Area. On Tue, Jun 2, 2015 at 5:08 PM, Graham Cox <graham....@bigpond.com> wrote: > >> 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
