• foobar <foo bar.com> Jan 31 2011
• Walter Bright <newshound2 digitalmars.com> Jan 31 2011
• so <so so.do> Jan 31 2011

foobar <foo bar.com> writes:

Walter Bright Wrote:

 foobar wrote:
 Java (the language itself) is mediocre at best but the Java standard
 libraries are excellent with comprehensive usable documentation to boot.
 
 Phobes is half a notch above c++ stdlib which is the worst ever from a
 usability and readability perspective. Are we still using G-d files? really?


 Please take a module or function in the phobos documentation, and rewrite it
to 
 how you think it should be done and post it, as an example of how to do it 
 right. We welcome such help.


My complaint is not about the implementation itself as it is about it's API. 
Java is an excellent example of many very usable APIs, meaning that it very
easy to both read Java code and understand what the functions do and write code
that's just as readable *without* RTFM. 

When I learned C++ in university, my notoriously demanding professor said that
code should be self documenting and that comments are meant to compensate for
poorly written code. 

Walter Bright <newshound2 digitalmars.com> writes:

foobar wrote:
 Walter Bright Wrote:
 
 foobar wrote:
 Java (the language itself) is mediocre at best but the Java standard 
 libraries are excellent with comprehensive usable documentation to boot.
 
 Phobes is half a notch above c++ stdlib which is the worst ever from a 
 usability and readability perspective. Are we still using G-d files?
 really?


 it to how you think it should be done and post it, as an example of how to
 do it right. We welcome such help.


 My complaint is not about the implementation itself as it is about it's API.
  Java is an excellent example of many very usable APIs, meaning that it very
 easy to both read Java code and understand what the functions do and write
 code that's just as readable *without* RTFM.



Please take a Phobos module or a function, and rewrite its API to demonstrate 
your point.

so <so so.do> writes:

 Java is an excellent example of many very usable APIs, meaning that it  
 very easy to both read Java code and understand what the functions do  
 and write code that's just as readable *without* RTFM.


This one i don't understand. (seems i fail to understand many things  
nowadays!).
I have read the C++ standard library manuals many times, but still i find  
myself going back and reading it again occasionally.
Probably like my memory, STL also doesn't have the best of qualities.
But i have to ask, why would you target those that don't RTFM? It seems to  
me every language mainly targeting this kind of audience.