Clay language

Adam Ruppe destructionator at gmail.com
Wed Dec 29 05:49:00 PST 2010


spir wrote:
> These are imo essential documentation needs unfulfilled.
> 1. at import place, does not tell the reader which symbols
> are actually used

Two things: a) Why does it really matter at all? The specific
functions won't change the fact that you depend on the module.

b) Even if you grant that, what are the odds that such documentation
   would stay up to date as you remove the use of functions?

> 2. at use place, does not tell the reader where a given symbol
 is imported from

That introduces an unnecessary dependency on module implementation
details (unnecessary in the strictest sense - it compiles fine
without it!) If you want to determine that, you can consult the
documentation or the compiler.

>  For instance, I commonly use this scheme: [snip std.file]

I do that too in a lot of cases, where the module name is meaningful
and not redundant. Same for things like std.base64.encode, though
the new release makes the module namespace redundant...

Anyway, in some cases it gives good information. But what about
std.variant.Variant? Or std.json.toJSON? You're just repeating
yourself, and if you want to know where it is from, you can check
the imports and/or the documentation to easily confirm it:
http://dpldocs.info/Variant

Listing the name over and over again, and having to seek and change
it over and over again when other modules make a small change, just
adds a lot of work for no benefit. Besides, if you want docs on the
item, you have to look it up anyway.

> Maybe it's only me (and a few other martian programmers) expecting > code to be
commonly clearer...

You're assuming your way is, in fact, objectively clearer.


More information about the Digitalmars-d mailing list