www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - How to Design a Good API and Why it Matters

reply Alix Pexton <alix.DOT.pexton gmail.DOT.com> writes:
I had a quick look through the archives to see if anything about this 
talk by Joshua Bloch had been posted before, but couldn't find any 
references. Here are the slides...

http://lcsd05.cs.tamu.edu/slides/keynote.pdf

I think I remember seeing a (poor quality) video of the presentation too.

I'd be interested to hear what people think of these guidelines and if 
anyone has any other good API design resources to share.

A...
Sep 05 2011
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-09-05 11:55, Alix Pexton wrote:

 I had a quick look through the archives to see if anything about this
 talk by Joshua Bloch had been posted before, but couldn't find any
 references. Here are the slides...

 http://lcsd05.cs.tamu.edu/slides/keynote.pdf

 I think I remember seeing a (poor quality) video of the presentation too.

 I'd be interested to hear what people think of these guidelines and if
 anyone has any other good API design resources to share.

 A...


I basically agree with everything on those slides. Some things are Java 
specific and don't apply to D. For example, a final class can have 
public fields since D supports properties.

Another good read is the book "Clean Code": 
http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

-- 
/Jacob Carlborg
Sep 05 2011
parent reply Alix Pexton <alix.DOT.pexton gmail.DOT.com> writes:
On 05/09/2011 13:11, Jacob Carlborg wrote:


 Another good read is the book "Clean Code":
 http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882


Thanks for the recommendation! Looks like an interesting read, but my 
cursory glance through the index on Amazon didn't alight upon anything 
that specifically applies to API design (feel free to point out anything 
I may have missed).  Might be worth the investment, as it seems to cover 
a lot of best practice for general coding, documenting and testing tasks ^^

Any others?

A...
Sep 05 2011
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-09-05 15:09, Alix Pexton wrote:

 On 05/09/2011 13:11, Jacob Carlborg wrote:


 Another good read is the book "Clean Code":
 http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882


 Thanks for the recommendation! Looks like an interesting read, but my
 cursory glance through the index on Amazon didn't alight upon anything
 that specifically applies to API design (feel free to point out anything
 I may have missed). Might be worth the investment, as it seems to cover
 a lot of best practice for general coding, documenting and testing tasks ^^

 Any others?

 A...


This book is not explicitly about designing good APIs but it is, as you 
say, about best practice for general coding. If you follow these best 
practices you will get good APIs, so it's implicitly about designing 
good APIs.

As the slides describe, you always design APIs when writing code. The 
methods of a class are its API. A few ideas they both share:


* Both the slides and the book mention things like the importance of 
giving classes, methods and variables good names

* Both mention that the fewer parameters a method has the better

* Both mention that a given abstraction level (class, method, module and 
so on) should only do one thing and to it well. You shouldn't mix 
different levels of abstraction

There are many ideas like these that both the slides and the book share.

-- 
/Jacob Carlborg
Sep 05 2011
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-09-05 15:09, Alix Pexton wrote:

 On 05/09/2011 13:11, Jacob Carlborg wrote:


 Another good read is the book "Clean Code":
 http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882


 Thanks for the recommendation! Looks like an interesting read, but my
 cursory glance through the index on Amazon didn't alight upon anything
 that specifically applies to API design (feel free to point out anything
 I may have missed). Might be worth the investment, as it seems to cover
 a lot of best practice for general coding, documenting and testing tasks ^^

 Any others?

 A...


And I would highly recommend it, it's one of the best programming books 
I've ever read. It's well worth the investment.

-- 
/Jacob Carlborg
Sep 05 2011
prev sibling parent reply Mirko Pilger <pilger cymotec.de> writes:
 anyone has any other good API design resources to share.


http://www.amazon.com/API-Design-C-Martin-Reddy/dp/0123850037
Sep 05 2011
parent Alix Pexton <alix.DOT.pexton gmail.DOT.com> writes:
On 05/09/2011 14:44, Mirko Pilger wrote:

 anyone has any other good API design resources to share.


 http://www.amazon.com/API-Design-C-Martin-Reddy/dp/0123850037


At first I worried that this would be too C++ specific, but from what I 
have seen in the example pages the opening chapters at least are pretty 
general, with many ideas that are equally applicable to D and code that 
is (for C++) quite readable. The later chapters do seem to depend on C++ 
very heavily however, so while they might contain some patterns that D 
programmers can utilise or even improve upon, I suspect it may be harder 
to translate.

Anyone out there to second this recommendation?

A...
Sep 05 2011