GetDunne Wiki

Notes from the desk of Shane Dunne, software development consultant

User Tools

Site Tools

Trace:
api_guessing_game

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
api_guessing_game [2017/09/30 19:41]
shane [Signs that one is stuck in API Guessing Game] 		api_guessing_game [2017/10/01 14:44] (current)
shane [Read this even if you skipped to the bottom]
Line 9: Line 9:
  
 ===== Signs that one is stuck in the API Guessing Game ===== ===== Signs that one is stuck in the API Guessing Game =====
-  * Having to write "experimental" code for one specific function call, and run it repeatedly to observe whether or not it works, what the return values are, etc. +  * Writing "experimental" code for one specific function call, and running it repeatedly after little changes, to observe whether or not it succeeeds, what the return values are, etc... 
-  * Having no idea how to start implementing an operation using the library. +  * Having no idea how to start implementing an operation (even a common one) using the library... 
-  * Having no which parts of the library are fundamental and unlikely to change, as opposed to those which are still under development. +  * Having no which parts of the library are fundamental and unlikely to change, as opposed to those which are still under development... 
-  * Having high confidence that a specific class (or group of functions and data structures) is the right one for a specific purpose, but having no idea of the order in which the various functions are supposed to be called.+  * Being fairly sure that a specific class (or group of functions and data structures) is the right one for a specific purpose, but having no idea of the order in which the various functions are supposed to be called... 
 + 
 +//...because the authors didn't bother to write it down.//
  
-Each of the above implies the ending "because the authors didn't bother to write it down". 
 ===== Documentation hints for library developers/vendors ===== ===== Documentation hints for library developers/vendors =====
   * The greatest library/API design in the world is no use if programmers can't figure out how to use it.   * The greatest library/API design in the world is no use if programmers can't figure out how to use it.
Line 28: Line 29:
 Choosing to use someone else's code library and API is (or //should be//) a //buy-or-build// decision---I choose to use your code because it's more cost-effective than writing my own. So, Choosing to use someone else's code library and API is (or //should be//) a //buy-or-build// decision---I choose to use your code because it's more cost-effective than writing my own. So,
   * If I'm stuck using your code because there's no alternative (I'm looking at you, Microsoft and Apple), then your failure to provide and maintain adequate documentation is //abuse of privilege// and I will hate you for it.   * If I'm stuck using your code because there's no alternative (I'm looking at you, Microsoft and Apple), then your failure to provide and maintain adequate documentation is //abuse of privilege// and I will hate you for it.
-  * If your library is the best thing around, but your commercial license fees are exorbitant (I'm looking at you, [[https://www.juce.com/|Roli/JUCE]], Intel, and pretty much every DSP library provider on the planet), your documentation had better be first-class or I will look elsewhere.+  * If your library is the best thing around, but your commercial license fees are exorbitant (I'm looking at you, Intel, and pretty much every DSP library vendor on the planet), your documentation had better be first-class or I will look elsewhere.
   * If your library is free and/or open-source, I thank you from the bottom of my heart, and I realize your resources are limited, but consider your legacy. Either make an effort to provide documentation, or find a collaborator who can.   * If your library is free and/or open-source, I thank you from the bottom of my heart, and I realize your resources are limited, but consider your legacy. Either make an effort to provide documentation, or find a collaborator who can.
-  * Whoever you are, don't give me attitude. You may be very clever, but you're not //that// bloody clever.+  * Whoever you are, don't give me attitude. You may be very clever, but you're not //that// clever.
  
api_guessing_game.1506800508.txt.gz · Last modified: 2017/09/30 19:41 by shane

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution 4.0 International
CC Attribution 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki