PDF de programación - Cómo hacer una buena API

Akademy-es 2009
[email protected]

C´omo hacer una buena API

Albert Astals Cid

Julio, 2009

Albert Astals Cid — C´omo hacer una buena API

1/20

Akademy-es 2009

1 Cr´editos

2 Caracter´ısticas de una buena API

3 El proceso de dise˜no

4 Gu´ıas de dise˜no

Albert Astals Cid — C´omo hacer una buena API

2/20

Akademy-es 2009

1 Cr´editos

2 Caracter´ısticas de una buena API

3 El proceso de dise˜no

4 Gu´ıas de dise˜no

Albert Astals Cid — C´omo hacer una buena API

3/20

Cr´editos

Esta presentaci´on est´a basada en ”The Little Manual of API
Design”de Jasmin Blanchette, QtSofware, Nokia

Albert Astals Cid — C´omo hacer una buena API

4/20

Akademy-es 2009

1 Cr´editos

2 Caracter´ısticas de una buena API

3 El proceso de dise˜no

4 Gu´ıas de dise˜no

Albert Astals Cid — C´omo hacer una buena API

5/20

Caracter´ısticas de una buena API
Los 5 puntos

Es f´acil de aprender y memorizar
Hace el c´odigo m´as leible
Hace d´ıficil que te equivoques
Es f´acil de extender
Es completa

Albert Astals Cid — C´omo hacer una buena API

6/20

F´acil de aprender y memorizar
API para vagos desmemoriados

Nombres consistentes
Patrones consistentes
Predecible
Sem´anticamente coherente
Principio de la menor sorpresa
No demasiados convenience methods

Albert Astals Cid — C´omo hacer una buena API

7/20

C´odigo leible

El c´odigo se escribe una vez pero se lee muchas
En APL una l´ınea de 15 car´acteres sirve para calcular una
lista de todos los numeros primos hasta N
!Perl
Ser conciso no es una necesidad para la legibilidad

Albert Astals Cid — C´omo hacer una buena API

8/20

C´odigo leible (II)

Qt3:
slider = new QSlider(8, 128, 1, 6, Qt::Vertical, 0,
”volume”);

Qt4:
slider = new QSlider(Qt::Vertical);
slider→setRange(8, 128);
slider→setValue(6);
slider→setObjectName(”volume”);

Albert Astals Cid — C´omo hacer una buena API

9/20

C´odigo leible (III)

Qt Jambi:
QGridLayout layout = new QGridLayout;
layout.addWidget(slider, 0, 0);
layout.addWidget(spinBox, 0, 1);
layout.addWidget(resetButton, 2, 1);
layout.setRowStretch(1, 1);
setLayout(layout);

Albert Astals Cid — C´omo hacer una buena API

10/20

C´odigo leible (IV)

Swing:
GridBagLayout layout = new GridBagLayout();
GridBagConstraints constraint = new
GridBagConstraints();
constraint.fill = GridBagConstraints.HORIZONTAL;
constraint.insets = new Insets(10, 10, 10, 0);
constraint.weightx = 1;
layout.setConstraints(slider, constraint);
constraint.gridwidth =
GridBagConstraints.REMAINDER;
constraint.insets = new Insets(10, 5, 10, 10);
constraint.weightx = 0;
layout.setConstraints(spinner, constraint);
9 l´ıneas m´as...

Albert Astals Cid — C´omo hacer una buena API

11/20

Dif´ıcil de usar de forma incorrecta

P´agina 10 del manual

Qt3:
button = new QPushButton(this, ”Hello world”);

Qt4:
button = new QPushButton(this);
button→setObjectName(”Hello world”);

addItem vs insertItem

Albert Astals Cid — C´omo hacer una buena API

12/20

F´acil de extender

Espacio de nombres
ABI/API estable
d-pointer
no retornar referencias

Albert Astals Cid — C´omo hacer una buena API

13/20

Akademy-es 2009

1 Cr´editos

2 Caracter´ısticas de una buena API

3 El proceso de dise˜no

4 Gu´ıas de dise˜no

Albert Astals Cid — C´omo hacer una buena API

14/20

El proceso de dise˜no

Conoce tus requisitos
Escribe antes los casos de uso que el c´odigo
Mira ejemplos de API similares
Define la API antes de implementar nada
Haz que te revisen la API
Escribe ejemplos contra la API
Preparate contra extensiones
No publiques API internas
Ante la duda, ...

Albert Astals Cid — C´omo hacer una buena API

15/20

Akademy-es 2009

1 Cr´editos

2 Caracter´ısticas de una buena API

3 El proceso de dise˜no

4 Gu´ıas de dise˜no

Albert Astals Cid — C´omo hacer una buena API

16/20

Nombres

Nombres autoexplicativos (QPainterPath/QWorkspace)
Evita los booleanos
No uses sin´onimos (widgets/controls)
Orden de par´ametros
Similitud con clases existentes
No uses abreviaciones
Nombres espec´ıficos mejor que generales
No seas un esclavo de la API padre

Albert Astals Cid — C´omo hacer una buena API

17/20

Sem´antica

Escoge buenos valores predeterminados
No hagas tu API demasiado lista
Atenci´on a los casos extremos
Cuidado con las API virtuales

Albert Astals Cid — C´omo hacer una buena API

18/20

Estructura

Busca API basada en propiedades
La mejor API es la API que no existe

Albert Astals Cid — C´omo hacer una buena API

19/20

Akademy-es 2009

Gracias. ¿Preguntas?

http://www.kde-espana.es

Albert Astals Cid — C´omo hacer una buena API

20/20

Albert Astals Cid
[email protected]