Comments on: Documentation for Telepathic Developers http://gojko.net/2007/04/03/documentation-for-telepathic-developers/ The Quest for Software++ Wed, 07 Jan 2009 02:58:02 +0000 http://wordpress.org/?v=2.7 hourly 1 By: Stefano http://gojko.net/2007/04/03/documentation-for-telepathic-developers/comment-page-1/#comment-6629 Stefano Fri, 06 Apr 2007 17:26:36 +0000 http://gojko.net/2007/04/03/documentation-for-telepathic-developers/#comment-6629 Great post, definitely one of my favourites in the last weeks. Most of the times developers actually explore a new API by trials and errors and learn it by intuition, not with the complete documentation, so it is better to deal also with this approach. Great post, definitely one of my favourites in the last weeks. Most of the times developers actually explore a new API by trials and errors and learn it by intuition, not with the complete documentation, so it is better to deal also with this approach.

]]> By: paulo http://gojko.net/2007/04/03/documentation-for-telepathic-developers/comment-page-1/#comment-6492 paulo Wed, 04 Apr 2007 22:32:36 +0000 http://gojko.net/2007/04/03/documentation-for-telepathic-developers/#comment-6492 There's an attempt to make the kind of "transparent API" that you advoke in the AbstractDocument class. It defines a one writer many readers lock on each document so it can be used on many views, and all functions that alter the document invoke the lock. However they "forgot" to expose the lock, or a function that was lockless for altering the document. Result : copying things out of a document, applying custom text shaping and putting the text back on the document is much slower that it should be. The alternative would be to either subclass the document (and reimplement some horrible logic, quite impossible for most developers), reimplement the parser if our shaping is amenable to that (even more impossible). The lesson is, ofcourse to actually provide the mechanisms for the efficient case. (Another thing, the AbstractDocument again, gives a custom "unprotected String" that is mutable a "Segment" backed by the char array in the document. However there is no way to put the segment into a new document without 1) a toString() and (inside the AbstractDocumentClass) a String.getBytes (that allocates a new array to copy the string contents. The other lesson is "Take your abstractions to their logical conclusion". There’s an attempt to make the kind of “transparent API” that you advoke in the AbstractDocument class. It defines a one writer many readers lock on each document so it can be used on many views, and all functions that alter the document invoke the lock. However they “forgot” to expose the lock, or a function that was lockless for altering the document. Result : copying things out of a document, applying custom text shaping and putting the text back on the document is much slower that it should be. The alternative would be to either subclass the document (and reimplement some horrible logic, quite impossible for most developers), reimplement the parser if our shaping is amenable to that (even more impossible). The lesson is, ofcourse to actually provide the mechanisms for the efficient case. (Another thing, the AbstractDocument again, gives a custom “unprotected String” that is mutable a “Segment” backed by the char array in the document. However there is no way to put the segment into a new document without 1) a toString() and (inside the AbstractDocumentClass) a String.getBytes (that allocates a new array to copy the string contents. The other lesson is “Take your abstractions to their logical conclusion”.

]]> By: 800px http://gojko.net/2007/04/03/documentation-for-telepathic-developers/comment-page-1/#comment-6342 800px Wed, 04 Apr 2007 08:54:45 +0000 http://gojko.net/2007/04/03/documentation-for-telepathic-developers/#comment-6342 On the basis that most developers are the sort of people who will press buttons till something does what they want (and be proud of the fact) this makes complete sense. On the basis that most developers are the sort of people who will press buttons till something does what they want (and be proud of the fact) this makes complete sense.

]]> By: creaothceann http://gojko.net/2007/04/03/documentation-for-telepathic-developers/comment-page-1/#comment-6233 creaothceann Tue, 03 Apr 2007 21:50:20 +0000 http://gojko.net/2007/04/03/documentation-for-telepathic-developers/#comment-6233 Great article. "if Clean() should be called anyway, then just call it internally" Yes, but hopefully there's a "dirty" flag that skips cleaning when not required. Great article.

“if Clean() should be called anyway, then just call it internally”
Yes, but hopefully there’s a “dirty” flag that skips cleaning when not required.

]]>