Brad Abrams on various language features and how to use them in APIs
Brad offers some practical advice - a few highlights:
- don't make your consumers "archeologists" - leave artifacts that help developers understand the intent of your object model - make intent obvious
- Const/ReadOnly: readonly better than const if values might change
- Namespaces: use to organize classes, ensuring that the most-used classes are the most available, hiding the more advanced classes in sub-namespaces
- Classes:
- ensure that they have a clear purpose - better to go overboard on classes named in a concrete fashion, rather than having too many abstract-named classes
- think about what the developer will think the class does and whether this is obvious
- once again, constructors should be used to capture state on instantiation - shouldn't do much work
- Enums:
- the default numbers assigned to enum values actually do matter since calling assemblies use the number vs. the name
- values should be specified explicitly in a framework assembly scenario
- flags enum names should be plural
- Properties: use for cases when there is a "logical backing" for the property