The discussion about the merits of comments, and the passing remarks on
variable-naming conventions, external documentation, tools and dominant
programming idioms, seem to be talking around a more general topic,
which is: "writing readable code". In the process, I think it's leaving
unstated the question: "readable by whom?" I believe one has to address
that before useful results can be arrived at, since there are many potential
audiences for code with clearly differing requirements.
For example, I will write code differently, including how I comment it, if
I'm writing it for a client than if I'm writing it for a colleague. In
general, this is because I have much more information about what the
colleague will need to know to make sense of it or to adapt it, and
what would be superfluous or even condescending for a colleague might be
essential for a client.
Other audiences for code I have worked on have included:
+ people who will work on it in future who will have no opportunity to
ask me questions about it;
+ people who have never programmed in the domain before, but who know
the language well;
+ people who have never programmed in the language before, but who know
the domain well;
+ people who have never programmed before;
+ people who must certify the code;
+ people who must port the code;
+ people who are the principal developers of a system I'm making
changes or enhancements to;
+ people who want to migrate particular sub-sections of the code into
a completely different project;
+ myself, two years hence, when I've forgotten what tricky workarounds
I had to devise to make the code work on some earlier platform.
(I'm omitting the obvious 'audience' of the compiler or interpreter, since
I believe that code is first and foremost for human consumption, not any
machine's.) Because of all this, I don't believe it's appropriate
to make comments (sic) about whether comments are worthwhile or not, without
first establishing who's reading the code, what they know, and what their
intent is in reading the code.
Perhaps I've misunderstood, but the original question (by Dave Marin) seems
to have the implicit assumptions that:
+ "programmers" can be lumped together for the purposes of studying
how they comment code;
+ "commenting" describes a uniform activity that crosses languages
and environments;
+ and that the various potential audiences for the commented code are
equally served by what programmers produce.
I think these points need to be considered explicitly, rather than all of
us assuming that we all agree on what these things mean, before studies
like Dave's can produce something of value.
--
Frank Wales [[EMAIL PROTECTED]]
- Automatic footer for [EMAIL PROTECTED] ----------------------------------
To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss
To join the announcements list, mail [EMAIL PROTECTED] subscribe announce
To receive a help file, mail [EMAIL PROTECTED] help
This list is archived at http://www.mail-archive.com/discuss%40ppig.org/
If you have any problems or questions, please mail [EMAIL PROTECTED]
