Be wary of "required" properties that must be explicitly set correctly in order for the object to function (especially if it's not obvious). 

I recently got burned by this, and it's certainly a frustrating problem to diagnose. In my case, the function didn't give an error and just silently nop instead of doing the right thing. The docs were worthless, so I tried a few properties with promising names, but there were too many to find the right combo. I eventually searched around for a sample usage, saw the missing property, and got things working.

 

My plea to library designers:

  1. If a property is truly necessary, make it a parameter to the constructor.
  2. Else, can you at least pick a good default? For example, if it's a "thickness" property for drawing a line, "1" is a great default value.  If developers aren't happy with the default, they'll see the line is too thin and figure out which property to set to make it thicker. That's much easier to diagnose than seeing no line at all.
  3. If you really can't pass it to the ctor; and you just can't pick a good default, don't just silently fail - consider throwing from the operation with an exception message that tells you to set the property.
  4. As the very least, clearly document that this is required.

 

Related links: