Dizajnimi i API-ve që Plaken Bukur

API-të më të mira duken të vetëkuptueshme kur i shikon prapa. Thërret një metodë, ajo bën të vetmen gjë që premton emri i saj dhe vazhdon të sillet ashtu përgjatë një duzine versionesh. Ai besueshmëri nuk është fat. Është rezultat i një grushti vendimesh të marra herët dhe të mbrojtura me kalimin e kohës.

Emërto gjërat për thirrësin, jo për implementimin

Një API është një premtim i shkruar në emrat e metodave. Kur e emërton një funksion sipas mënyrës se si punon nga brenda, çdo ristrukturim rrezikon ta thyejë atë premtim. Emërto sipas asaj që dëshiron thirrësi, dhe implementimi mbetet i lirë të ndryshojë poshtë tij.

Testi është i thjeshtë: lexoje me zë vendin ku bëhet thirrja. Nëse një koleg i ri mund të hamendësojë çfarë ndodh pa e hapur kodin burimor, emri po e bën punën e vet.

Bëje rastin e zakonshëm pa mundim

Shumica e thirrësve duan të njëjtën gjë pjesën më të madhe të kohës. Dizajnoje rrugën e paracaktuar që të mos kërkojë asnjë konfigurim, pastaj shto opsione sipër për rastet e rralla. Një API që kërkon pesë parametra për një detyrë rutinë do të mbështillet në një ndihmës nga ekipi i parë që e përdor, dhe tani mban dy ndërfaqe në vend të njërës.

Çdo argument i detyrueshëm është një taksë e vogël që ngarkon në çdo thirrje të vetme. Ngarkoje vetëm kur vlera vërtet nuk mund të nënkuptohet.

Versiono kontratën, jo kodin

Ndryshimet që prishin përputhshmërinë nuk janë armiku. Surpriza është. Kur duhet të prishësh diçka, jepi një emër të ri ose një version të ri dhe lëre rrugën e vjetër të vazhdojë të punojë përgjatë një dritareje të qartë vjetërsimi. Thirrësit do ta falin një migrim që mund ta planifikojnë. Nuk do ta falin një ndryshim të heshtur që prish prodhimin një të martë.

Një API që plaket bukur është ai për të cilin mund të pushosh së menduari. Ndërtoje ashtu që edhe njerëzit që varen prej tij të munden po ashtu.