[MyNameIsFred]

> In a sense, programming is all about what your program should do in the first place. The “how” question is just the “what”, moved down the chain of abstractions until it ends up where a computer can understand it, and at that point, the three words “multichannel audio support” have become those 9,000 lines that describe in perfect detail what's going on.

This closing paragraph is excellent.

While 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, the overall message here is very true and very well put.

When I made this realization for myself, it was a major turning point in the quality, speed, maintainability, and usability of the code I produce, especially when I can successfully define the final code structure to directly reflect this progressive refinement from intent to implementation.

[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.