Opened 12 years ago

Closed 10 years ago

#3054 closed defect (wontfix)

f considered harmful

Reported by: skinner Owned by: alex
Priority: low Milestone: future
Component: TestFramework Version: 0.9
Keywords: Cc:
Blocked By: Blocking:

Description (last modified by James Burke)

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.

Attachments (1)

doh_runner.patch (877 bytes) - added by skinner 12 years ago.
patch for util/doh/runner.js

Download all attachments as: .zip

Change History (13)

comment:1 Changed 12 years ago by Adam 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.

Changed 12 years ago by skinner

Attachment: doh_runner.patch added

patch for util/doh/runner.js

comment:2 Changed 12 years ago by skinner

Component: GeneralTestFramework

comment:3 Changed 12 years ago by skinner

see attached patch

comment:4 Changed 12 years ago by 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.

comment:5 Changed 12 years ago by 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.

comment:6 Changed 12 years ago by 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/


comment:7 Changed 12 years ago by 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.

comment:8 Changed 12 years ago by 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.

comment:9 Changed 12 years ago by Adam Peller

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

comment:10 Changed 12 years ago by dylan

Milestone: 1.4

comment:11 Changed 10 years ago by James Burke

Description: modified (diff)
Milestone: 1.4future

comment:12 Changed 10 years ago by Adam Peller

Resolution: wontfix
Status: newclosed

This one has expired.

Note: See TracTickets for help on using tickets.