Every once in a while I get asked why doesn't JSDuck support a
certain character in the names of various entities. The character is
usually some punctuation like the dot (
.) or dash (
-). The names
in question are the names of classes and class members (methods,
properties, events, etc).
So why doesn't JSDuck allow you to document a class named
My.Special-Class or method named
my+method? Why doesn't the
freaking tool just get out of the way and allow you to do what you
want? Supporting just one more character can't be so hard - why not
simply do it?
So when I implement support for dash and dot, the next user comes along and asks why doesn't JSDuck support colon? Then the third one comes and asks to support spaces. Soon we're talking about supporting the whole Unicode including Egyptian hieroglyphs.
only when using proper identifier names will they be convenient to use:
So, by only allowing proper identifier names, JSDuck is asking you to take the sensible route.
The main thing here is that JSDuck is opinionated. It wants you to write your code in a certain way. And if you want to do things differently it's going to be painful. In that case you might have chosen the wrong tool.
In addition to the above, supporting the whole range of possible characters is far from easy to implement. Even adding support for just one more punctuation character is a considerable amount of work.
There's a lot of convenience that derives from the assumption that class and member names are always proper identifier names. It allows us to use the same names in URL-s, HTML id-s and other generated code without a need to do additional escaping.
For example when supporting dot in member names, we need to ensure we encode the dot somehow when using the name inside HTML id attribute, because the following is not valid:
JSDuck is already doing this kind of escaping to support the
id. So an identifier
S-foo in HTML. Not a prettiest
tool to support.
But supporting all kinds of other characters is just complicating the code base while helping only a rary minority of users who want to do some weird things.
Finally, using non-identifier names for classes and members is just
asking for trouble. Even if JSDuck implements a support for it, you
will soon face some other tool which also chokes on your
unconventional code. Sure, you can have a slash (
/) in your class
names, but good luck with your filesystem if you want to save it into
a file with the same name.
Kirjutatud 17. septembril 2012.