Re: About method comments

But is that any reason to denigrate the theory and its proponents?

A number of counter-arguments have already been made in this thread,
many people have spelled out the costs and the problems incurred by not
adequately documenting code, and so the ball is in your court to offer
some genuinely compelling refutations. If, instead, you want to ignore
the substantive points and take issue with the tone of certain
messages, calling them "sly" etc., okay, but I don't see how that
really strengthens your case.

As for splash damage to documentation in general, how can that
be attributed to a coding style that doesn't require code comments.
If overall documentation is lacking, code comments aren't going to
fix the problem.

This does not capture Vassili's point. You need to re-read his post and
re-phrase your response.

As I said, someone needs to decide to devote the
necessary resources. By not devoting those resources, maybe the
management has recognized the tradeoff.

Heh. Management? I'd be very surprised if management had any clear
sense of this problem at all. Maybe *that's* part of the problem. For
example, let's take the case you mentioned before. The developer lands
in a project with a six-week deadline and his only course of action is
to hack something together that works. There's no time to write
documentation, no time to make the code comprehensible to anybody other
than the two developers he pair-programs with. If management organized
such a project, I would consider it a failure at a higher-level of
planning that the developers were forced to shoulder. At the end, the
managers will of course slap the developers on the back for a few
minutes and make them feel like heroes for saving management from a
potential failure.

My questions would be: Were the developers' time estimates solicited?
Was there a discussion/negotiation with management about
deadlines/deliverables or was the project run via top-down orders? I
assume the developers said: "OK, but you're not going to get any
documentation with that deadline", and what was the response? Did
management actually do the sort of detailed cost-benefit analysis you
are advocating? You said "maybe" they recognized the tradeoff, which
suggests that in your case you either didn't know or didn't ask. If
they did such an analysis, can you share their data and their
rationale?

If you don't recognize tradeoffs, but instead stick to (possibly)
out-dated notions of code "goodness", then you may just earn yourself
last place, because the rest of the world sees a tradeoff.

Hmm. First you say "possibly" out-dated and then you say that the rest
of the world sees a trade-off as if it's a fact. Does the rest of the
world really see a trade-off, or is this just a speculation on your
part that there might "possibly" be a trade-off? If it's really "the
rest of the world" maybe you could give us some references to studies
and analysis of the problem.

Since you are arguing against a lot of hard-won wisdom in the industry,
and since a number of anti-comment practices have been shown to have
clear costs, and since we have ascertained that XP hasn't come out
fully against comments (though there are developers who invoke
practices associated with XP and say those practices obviate the need
for comments), I think the burden is now really on you -- not those who
advocate comments -- to make a more compelling case.

Regards,

M. Roberts
Cincom Systems, Inc.

.

Relevant Pages

  • Re: No wonder Borland Technical Documentation stinks
    ... I'd warn developers about being dismissive in regard to ... Documentation exists, there is still the factor of basic competence. ... Competence as a metric to be tracked and enforced is a management ...
    (borland.public.delphi.non-technical)
  • Re: Perplexed in a SW group..
    ... To be more salable to management you will probably have to ... Such legacy code is going to be a long-term problem for you. ... you need to sell other developers that the change is ... they are off developing data collection tools on their own time to ...
    (comp.object)
  • Re: systems programming versus application programming
    ... IMO the core reason for that failure rate is that software developers do ... They are too absorbed in the Cult of Creativity to do ... management (e.g., poor estimates, insufficient resources, unrealistic ... them by pushing back on every schedule item. ...
    (comp.object)
  • Re: Programming PowerPC on Mac
    ... The documentation about how to program Windows with assembly language was, ... Linux and X and such with LuxAsm...because, over on Linux, it's the same ... There's nothing "official" only what ordinary developers (like ...
    (alt.lang.asm)
  • Re: convincing a client to go with dotNet instead of Access project
    ... That would be good documentation to have... ... > -learning curve for language, APIs, deployment management, etc ... > -Access really tops out with performance after six concurrent connections ... >> I believe a dotNet solution is better, but I'm trying to be as ...
    (microsoft.public.dotnet.general)
Loading