All the Perl that's Practical to Extract and Report

It's all about the names

samtregar on 2005-08-07T22:40:50

Working on MKDoc can be hard. It's a great system in many ways but every so often I get completely lost. I'm starting to think that fundamentally it's a naming problem. For example, consider the word "editor." MKDoc uses "editor" to mean four different things:

  1. The table which holds all users is called Editor.
  2. A user is considered an "editor" if they have editing rights to at least one document.
  3. The code that controls the part of the UI where users edit content is called an "editor." The base class is flo::Component but all the sub-classes live in flo/editor.
  4. The code that allows a document to be loaded and saved to the database lives in flo::Editor. This one is the hardest to characterize - it's probably implementing a design-pattern I don't know. Maybe the "editor" pattern? God, I hope so.

All this means that when you see a variables called $editor in MKDoc you really have no idea what you're dealing with. It could be a user, a specific type of user, a UI editor or an abstract encapsulation of the act of editing a document. That's hard.

So please, people, get your names right from the start. And if you can't get them right at least be consistent and careful. Having even two things named the same is bad. Having four is like declaring war on maintainance programmers.

-sam