.. _startingOver:

.. WARNING: DO NOT EDIT THIS FILE:
   AUTOMATICALLY GENERATED.
   PLEASE EDIT THE .py FILE DIRECTLY.

Music21’s Mistakes
==================

So, you’re a developer. Maybe you hate Python or you hate ``music21`` or
you think (whenever you read this) that ``music21`` was cool for its
time, but it’s time to create a new system from scratch.

I’m never going to do that: I know about the `Second System
Effect <https://en.wikipedia.org/wiki/Second-system_effect>`__ and know
that I couldn’t do it right.

But if you’re interested, here are the mistakes I made in ``music21``
that I know of that are too late to change now, but that I’d avoid if I
were you:

1. Most objects should be immutable. Maybe Streams can’t be, but
   definitely Pitches, Accidentals, Durations, etc. Then they would be
   hashable and equality operators would work the way Python and most
   other languages intend them to be. But as it is, we have a situation
   where we need to know that Streams compare on identity while lists of
   notes compare on equality. If you don’t have a handle on the
   difference between the identity and equality, do yourself a favor and
   become an expert before writing your system. I didn’t know and now
   things are awful in this respect.

2. Because of point 1, I probably would store objects and sites
   separately and return them as a separate composite object; this would
   eliminate 90% of the deepcopying happening in ``music21``.

3. I borrowed ``-`` for flat from Humdrum thinking that there would
   otherwise be a lot of conflicts between octave signatures for B, like
   ‘BBB’ and ‘bbb’ and flats. It turns out that hasn’t been much of a
   problem.

4. Follow Liskov Substitution Principle. Violations of it are all over
   music21, and that’s been an issue as computers need to infer type
   better.

5. Use fewer properties except when they are fast to compute, and never
   let a property have a side effect. Modern IDEs are constantly
   querying all properties to see what that might contain. This is why
   ``.flat`` had to become ``.flatten()``.

6. Keep the core of the toolkit small and encourage an ecosystem of
   other add-ons.

7. Don’t try to encode every exception to standard music that your
   musicologist brain can conceive of. Put those in the ``.editorial``
   or other special purpose attribute.

8. Make every pitch have an accidental. The difference between
   Accidental(‘natural’) and None has raised more problems than its
   worth. (added June 2023)

There will be more here as I think of it. – Michael Scott Asato
Cuthbert, 2022 October.