Attributes and API usability revisited

re: Attributes and API usability revisited

chris hollander — Fri, 14 May 2004 12:23:00 GMT

a follow up study into "best case" uses of attributes would be great to read about.... in fact, i would enjoy participating in that research. :)

There are many instances in which attribution/decoration provides, IMHO, much cleaner, easier to understand access to otherwise complex functionality. declarative transactions come to mind; so does declarative data mapping between biz object schema and database schema. instrumentation is also a great candidate for declarative, attribute based APIs; i.e., wrapping methods in [Trace],[LogEvent], [IncrementPerfCounter].

Moving towards more declarative, aspect-ish API's is a Good Thing. I can understand people having difficulties with complex composition, and impacts on readability and such; if we were to move foward with this, we should look into mechanisms to improve the experience from a dev/ui standpoint.

re: Attributes and API usability revisited

Steven Clarke — Thu, 13 May 2004 16:48:00 GMT

Interesting comment. The API team had some good reasons for their use of attributes in this case. In particular, the attributes place certain constraints on the way that classes can use the API which means that the execution framework the classes plug into can treat all such classes consistently.

However, if the design of the API does not communicate this clearly, and instead communicates that the designers were just trying to look clever, then the design has obviously failed.

re: Attributes and API usability revisited

B.Y. — Thu, 13 May 2004 16:39:00 GMT

Let me guess the design process.

Hmm, we don't want to design just another boring API, how would that show off our brilliance and intellect ? So what should we do ? I know, core functionality thru attributes !

re: Attributes and API usability revisited

Steven Clarke — Thu, 13 May 2004 16:06:00 GMT

I think that at least some of the feedback that was obtained from the study is in agreement with your first point. Participants in the study did not appreciate or understand why they needed to both derive from some base class and use attributes on their class to achieve some functionality.

This was vital feedback to obtain - the team that designed the API had made certain assumptions that such a design was reasonable and would work well for their target customers. The feedback from the study suggested that this is not necessarily the case.

Regarding the rest of the results, I think we have good data to suggest that exposing APIs purely through attributes is not always perfectly fine. We most likely need to do follow up studies to determine the scenarios in which doing so makes more sense than the scenarios we considered in this study. Your example of exploiting security functionality through attributes could well be such a scenario in which it makes sense to use attributes. Clearly though, the data from this study indicates that there are also scenarios in which exposing APIs through attributes does not make sense. We need to collect more data so that we have a better understanding of the differences between these scenarios so that API designers know when it is reasonable to make extensive use of attributes and when it is unreasonable to do so.

re: Attributes and API usability revisited

chris hollander — Thu, 13 May 2004 15:49:00 GMT

ahem:

I am diametrically opposed to the premise of your study.

;) ok, maybe not quite, but actually, i do think that there is an important flaw in your method. from my reading, it sounds like you were asking participants to both derive from a base class AND use attributes... while its true that some parts of the BCL require this, I don't think thats in line with the intent of attributes.

Attributes are incredibly valueable when you have crosscutting concerns that cannot be implemented using common base classes. for example, the declarative security functionality is provided purely through attributes because it would have been impossible to require every class that needed declarative security to extend a common base class.

exposing API's purely through attributes is perfectly fine, especially if you want to preserve the ability for developers to inherit from their own base classes.