Chris tells
us about of Longhorn API review and in the process, lists some generally
useful design guidelines that can benefit any .NET development team. It seems
that API review is not a peer code review because it is done not by people involved
in actual coding of a component. It’s not a design review because the
team focuses on interfaces as oppose to their internal implementation.
Here’s my takeaway:
The team building the API had answers a standard questionnaire from the
review team, which includes:
- target users
- potential security problems
- representative sample code that users would be expected to construct.
Specific advice from reviewers:
- use best practice coding conventions in sample code
- support IDisposable at a macro level instead of a micro level
- expose collections from properties returning IEnumerable (not from the parent
object itself)
- prefer properties over Get/Set methods (as appropriate)
- don't tack the name of the enumeration type onto the enumeration values
themselves
- prefer overloads to parameters that can be null
- prefer typed parameters to object parameters
Points above
seem to be aligned with these guidelines.
