Drupal API should not require hook_facepalm

How many times have you been coding something and it doesn't work even though you've used an api/function call hundreds of times before?  I ran into this the other day with node_load().  For those of you use the node_load function, can you tell me how many arguments it has and what those arguments do (without looking at api.drupal.org?  I know, some gurus can, but can the average module developer do it?)

In this instance, I created a module that was updating data from a MSSQL install on existing nodes.  After I did my node save I needed to do a node_load of the node I created/modified (some steps happened in between with other modules), modify some of the data and then save it again.  The only problem is, when I did my second node_save() my first save's data was wiped out.  After turning on debugging I found that my first (SQL) update worked properly but my second update was using data from before my first update.  How could that be, I did a second node_load (they were in different functions)?  It turns out that node_load was using a cached version of the node.

I'm not dogging the internals of node_load, it's a fine function and if I was a sailor on leave at a bar, I would ask it to dance.  In fact, I've had to employ it's caching abilities quite often so don't take this as some type of Drupal sucks post, I hate the core developers or cheesy link bait.

What I was doing isn't really the point of this post nor is how node_load works.  It's the argument order and the default argument that I'm against.  Yes, I'm writing a ~200 word post about three arguments in one function.  I don't like the fact that the third argument, "reset" is defaulted.  There, I've said it.  The entire problem I had (yes, it was my fault) would have been much easier to debug if the argument did not have a default value.  This way, when I called node_load(123) I would have received a PHP error stating that I was missing an argument for the function.  Think about it, if there is no default, you would have to put true or false there (in this case, it would have forced me to read the documents).

I am aware that having an API use sane defaults is SOP and this issue affects a fraction of a fraction of developers but I believe it's a bad practice that encourages programmers to not pay attention (I know, I know, I rush, I'm the king of this.  On the other hand don't most developers have some type of impending deadline?)

So what's the point of this rambling tirade?  In the small scope I want the order of node_load to be changed and one of the defaults to be removed (Drupal 8 perhaps).  For the big scope I would like to hear from the community about other functions that have defaults that might hide bugs.  I'm not just doing this because I'm too stupid to read the docs, I would like to move forward for D8 in reviewing the API for these types of gotchas that can seriously lower the frustration level of non-Drupal-guru developers.  Please let me know your thoughts.