TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
As I see it, the question of the possible replacement's competence or lack of it is irrelevant. As tech writers, our job is to make things clear for other people. It's not a matter of trying to lessen the impact of the employers' bad hiring decisions, it's a matter of doing a job.
Assuming the time is available...If we have the opportunity to do it, putting comments in code is just doing our jobs. If the programmers are the ones who would do any commenting, I can't think of a good reason why they shouldn't.
I think the best reason for commenting code is the fact that code must be maintained throughout the full life cycle of the product. To be maintained efficiently, it has to be understandable. Comments can make it easier to understand. That makes the code easier to maintain.
________________________________
From: phil stokes <philstokes03 -at- googlemail -dot- com>
To: Keith Hood <klhra -at- yahoo -dot- com>
Cc: Tony Chung <tonyc -at- tonychung -dot- ca>; "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Sunday, March 31, 2013 9:09 PM
Subject: Re: Commenting Code (was Re: An interview question)
On 1 April 2013 08:49, Keith Hood <klhra -at- yahoo -dot- com> wrote:
But when you get run over by a bus and your job is taken by a guy with only half your experience, that guy will need help.
I find this way of putting it unconvincing. Do we have an ethical obligation - and is it ethical to spend our employers time now - engaging on activities to ameliorate the possibility that our employers will hire someone incompetent in the future?
I suppose this is a species of the larger argument about whether we should document our working practices in general for future project owners. I know that argument has been had on this list before, and I don't particularly want to get it into it here (my view on that is its situation specific).
I'm more interested in what's the BEST argument for commenting code or recommending commenting as 'best practice'. Thus far, I think Nick's given some good reasons, but I'd be interested to hear more arguments, for or against.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>From our sponsor Doc-to-Help: Want to see a Doc-To-Help web-based Help sample with DISQUS for user commenting?
