Re: commenting, was Re: Use of declare blocks

I think we mostly agree. It's bad to have a machine cluttered with files,
or code, that you think might be useful, but in fact it's so poorly
described that it can't be found, or understood when it is found. So the
system should force throwing away such things. If you truly think you
might need it in the future, you should adequately describe it now, before
you've forgotten.

Sometimes you know the code or file you are creating is "for the ages" and
you spend the necessary time thoroughly documenting it. But often you
don't know for sure, and think the likelihood of future use is low, so
spending a lot of care is a probable waste of time. Minimal documentation
is then appropriate. Rather than having two levels - minimal docs/full
docs - and going from level 1 to level 2 when you need the program the
second time, I suggest several levels, with transitions dependent on your
estimate of the likelihood you'll need it again, and the rate of decay of
your memory.

For example, in developing a binding to some API, I do a lot of throw-away
programs to test that I understand the API calls correctly. I then
document the binding. But then a few years later, on some newer project,
I recall "I once did a program that did much of what I need now, I wonder
where that old program might be." I'd like to either know that program is
definitely long gone, don't waste time looking for it, or else have a file
description that lets me easily find it, and internal documentation that
makes it easy to refresh my memory, to help with today's project.
.

Relevant Pages

  • Re: Using "new function() {...}" as a Singleton
    ... their documentation). ... to a solid foundation for the "major" libraries and frameworks. ... Even worse when the main goal of the API ... We are talking about selector *queries* (e.g. Selectors API). ...
    (comp.lang.javascript)
  • Re: Using "new function() {...}" as a Singleton
    ... their documentation). ... to a solid foundation for the "major" libraries and frameworks. ... The idea of copying an API without knowing what the expected outcome of its core method is ludicrous. ... And if you want to know why the section of CSS 2.1 that defines "identifier" was quoted, the pertinent part of the spec that makes reference to the term `identifier` is in CSS 2.1 is described in attribute values. ...
    (comp.lang.javascript)
  • Re: Tired of 100s of stupid Getter/Setter methods
    ... seeing as you're now scratching for even more marginal cases to ... >>reading the documentation that the library developer wrote. ... > ability to become familiar with an API. ... >>been ignoring real bugs in favor of some syntactic sugar. ...
    (comp.lang.java.programmer)
  • Re: Bluetooth application development
    ... It's a VERY complex API, maybe the most-complex that I've seen for Windows. ... Why MSDN is not providing enough documentation to develop application from ... I don't see any way to truely automate pairing; ... Here also i have to start the pairing process then Headset profile ...
    (microsoft.public.windowsce.app.development)
  • Re: Code density and performance?
    ... Heck, IPF memory requirements make ... It wasn't when the Alpha was designed. ... |> You mean the "POSIX" documentation, ... |>> You may regard breaking standards without even documenting the ...
    (comp.arch)