[tremon]

I do wonder if the author's progress along these wouldn't have been accelerated if more of this evolution took place before the first line of code

Doesn't that require much more thorough interface specifications and documentation than we have now (industry-wide)? I don't do that much software development anymore, but I have always been put off by the amount of trial-and-error required because of ill-defined interfaces.

[MyNameIsFred]

This is true.

I must admit that my more recent, positive experiences are only possible due to my accumulated understanding of my dependency chain and toolkit. I work on multiple things, but my largest, indefinitely-running one has only a single dependency...but it's a truly beastly, poorly documented enterprise system. It took me almost 2 years before I properly understood the system's intended usage, interfaces, intents, bugs, and pitfalls.

The JavaDocs are awesome in their uselessness:

  /**
   * Sets the Wimbulator.
   *
   * @param wimbulator
   *     the Wimbulator to set
   * @param identifier
   *     the identifier to use
   * @param flags
   *     flags
   * @param legacy
   *     used to apply legacy
  */
  public void setWimbulator(Wimbulator wimbulator, String identifier, long flags, boolean legacy);

[JoeAltmaier]

Hey! That's every JavaDocs I've ever encountered. See the Apple CoreAudio docs for instance. Auto-generated and never revisited.

Such doc systems are a crime - the Manager asks "Is the documentation complete?" and then Engineer says "Well the auto-docs were created but..." and the Manager says "Good, lets move on"

[majewsky]

On the other side of the spectrum, we have something like the Qt documentation: https://doc.qt.io/qt-5/qwidget.html

[clifanatic]

Which is a step up from the documentation you get (if you get any at all) in custom development:

    /**
     * The constructor
     */
    public Wimbulator(boolean q)

[douche]

Wow, those are awesome compared to most of the docs for the obtuse, wildly popular enterprise system I match wits with.

I resort to decompiling.