lang's should document pragmatics

7.21: adda/doc's/intended use as related to resources used:
. here is part of Python's Recommendations
for a library's coding style:

"( Code should be written in a way that
does not disadvantage an implementation of Python
For example, CPython's a += b or a = a + b
is an efficient implementation of
in-place string concatenation;
but in Jython,
the ''.join() form should be used instead.
This will ensure that concatenation occurs in
linear time across various implementations.)

[ie, jython is about java is about oop;
and if you have something like
( a = a op x ) to say in {oop, java, jython}
the oop way to do that is a.op(x)
and if you're a big oop fan and said
( a = b op x )
it's assumed you would never do so for
the case where (a) is the same as (b) .]
--
. this reminded me that part of
documenting a language
should be not only what the resource usage is,
but also the intended application;
ie, it should warn you if it's
not the most efficient way to do something
and point you to what is .