f considered harmful

[skinner]

f is an especially poor choice for a public function name, if our goal is to make the code easy to read and understand.

quoting from the dojo style guide:

11. All names SHOULD be written in English.

14. Public names SHOULD ... avoid unclear shortenings and contractions

Any violation to this guide is allowed if it enhances readability.

If you've got no idea what method this bug report is talking about, that's my point. If you're trying to figure out what f is and what it does, try searching for "f" in the Dojo API Reference, or grepping for "f" in the source code.

[peller]

This is a dup of #68, which I don't think has been very effective either (though leaving one open for checkins might be reasonable). Given that we already have a style guide which says this, I don't see the point in burdening the bug system with this unless we want to cite file references and handle this on a one-by-one basis. I'm guessing Brian may be concerned mainly about checkins to _base.

[skinner]

patch for util/doh/runner.js

[skinner]

see attached patch

[alex]

I can't say that I'm interested in this patch. We're talking about something you use in testing code only, at which point you want things to be short and easy to get at.

[skinner]

The unit tests won't be downloaded by end-users as part of any app, so we don't need to keep the testing code as short as possible to reduce file download size

One of the reasons to have unit tests is because they are useful as documentation for people who are learning about the code. The tests are more useful for newcomers if they are easy to read and understand. Making code easy to read and understand seems just as important as making the tests easy to write.

[skinner]

By adding t and f to the test framework, we've added surface area to the API, decreased consistency between test files, and make the dojo unit tests harder to explain and digest.

The slides and notes from our January Dojo Developer Day talk about our goals for Dojo 1.0. In getting from 0.4 to 1.0, one of the big goals was to make the Dojo APIs simple and clear. Here are a few quotes from the meeting notes, and some excerpts from the slides from the talk that Alex and Dylan gave:

---

why is dojo hard?

• too much surface area
• lack of consistency. No narrative voice.
• wasn't developed for people who aren't us. 95% is explaining and cutting things out
• digestability

http://dojo.jot.com/3D2

---

Getting Dojo To Great

Coherent Experience

"Simplicity is prerequisite for reliability." - Edsger Dijkstra

"Simplicity does not precede complexity, but follows it." - Alan Perlis

Users Think They Want Features

They Want Features They Can Master

Unusable Capability Is Worse Then Nothing

Our Job Is To Make Devs Look Good With Less Frustration

http://alex.dojotoolkit.org/07/3D2/Opening/

---

[bill]

We discussed this at today's meeting with resolution that Alex will try supporting true/false/equals as functions names, and if that doesn't work than do something else.

At the meeting, opinion was divided on whether t/f/e was better/worse than assertTrue/assertFalse/assertEqual. Most people seemed to think that we shouldn't have two aliases for the same function though.

[skinner]

Another option would be to follow the lead of Firebug, and only support a single function, "assert". That would reduce the surface area of the doh API, and make doh more consistent with Firebug.

Getting rid of assertEqual would help to make the tests more explicit and less magical. It would be more clear whether a given test was meant to test for identity (===) vs. equality (==) vs. shallow-object-equality vs. deep-object-equality.

[peller]

...but then you can't do cool stuff like say "value was 8 - expected 10"