4 ms·
Of course, your examples shouldn’t just be brief two-line snippets. As Rich Bowen of the Apache project puts it, “One correct, functional, tested, commented exa
by cobrausn 13y ago
Of course, your examples shouldn’t just be brief two-line snippets. As Rich Bowen of the Apache project puts it, “One correct, functional, tested, commented example trumps a page of prose, every time.”
If HN allowed signatures, that quote would be mine. I grok libraries and other people's code so much faster when I have a good working example, and the mere existence of that example makes me 10x more likely to use the lib (or, when I have no other option, 10x more likely to complain less).
- angersock 13y agoThe Three.js project has really shit documentation for most things, but they have scrupulously-maintained examples for their library which serve to answer most questions.
- general_failure 13y agoCare to give a few examples of where three.js docs are lacking?
- angersock 13y agoJust a bunch of todos for the semi-auto-generated stuff, lots of missing information about how the whole thing fits together. Not clear what is core functionality and what is well-maintained extensions for the examples (OBJ loader, etc.) It's a great library, don't get me wrong--just not the docs I'm looking for. I've been meaning to contribute back to help with this issue.
- Apreche 13y agoThis is 100% true. I am constantly frustrated by incomplete code examples in documentation. The one thing in particular that bothers me the most are when Python snippets don't show the import statements. do_magic(param, other_param) Where do I import do_magic from?!?!
- Cyranix 13y agoSame thing in Java -- if there's a class named something commonplace like "Transaction" or "Connection", it's going to be pretty critical to understand whose implementation that refers to.
- kamjam 13y agoSame in .Net, although Resharper (http://www.jetbrains.com/resharper/ http://www.jetbrains.com/resharper/) has made my life a lot easier by giving me much better import/using suggestions, although not 100% foolproof.