참고하면 좋을 내용이 있어서 해당 글을 그대로 가져오려고 한다. 대신 적으면서 내용을 한번 더 곱씹도록 하자.

원본 : Python API Checklist

간결함

• README에서 샘플 코드 제공 사례: Pendulum의 README는 샘플 코드로 시작한다.
• 보일러 플레이트 코드 줄이기: 처음으로 유용한 API를 호출하는 코드까지의 라인 수 세어보기 사례: urllib2 와 requests 라이브러리 비교, requests가 보일러 플레이트 코드가 적다.
• 유즈케이스 문서화하기 사례: python-social-auth 라이브러리는 일반적인 유즈케이스들을 문서화하고 있음.
• 단계적인 정보 공개 실천: 타당한 기본값 사용
  • 인자의 기본값은 가장 일반적인 유즈케이스에서의 값으로 결정
  • 성정의 기본값은 가장 일반적인 유즈케이스에서의 값으로 결정
  • 인자 순서는 사장 많이 사용되는 것부터 나열하고 관련괸 것들끼리는 그룹핑 사례: JavaScript의 history.pushState는 state, title, URL의 인자 순서를 갖고 있는데, 이는 별로 좋지 않음. 대다수의 API 사용자는 history에 URL만 추가하는 상황인데 state와 title를 지정하도록 강제하고 있음
  • 코드 스니펫의 복사/북여넣기가 필요없게 만들기
• 다루기 번거로운 입력(input)은 지양하기
  • 파라미터명에 오해의 소지가 있는지 확인하라
  • 사용자가 API를 호출하기 위해 무언가를 인스턴스화하고 있는지 확인하라
  • 커스텀 타입을 빌트인 바입으로 대체할 수 있는지 또는 둘 모두를 지원할 수 있는지 학인하라
• 최대한 사용자를 놀라게하지 말아야한다 (POLA, Principle of least astonishment) 법칙 따르기 법칙 따르기: “만약 어떤 기능이 예상치 못한 일을 많이 일으킨다면, 이는 재설계가 필요할 수도 있다”
  • 기본 동작이 클라이언트가 기대하는대로 돌아가는가?
  • 기본 동작이 성능, 부작용, 안정성, 보안, 제한 등에 대한 클라이언트의 기대치와 일치하는가?
• 추상화
  • 솔루션이 물리적으로 어떻게 동작하는지보다는 본질적으로 무얼 하는지에 초점을 맞춰라
  • 추상화되면 안되는 API가 있는가? 허술한 추상화의 법칙을 주의하자
• 파이썬답게 (Be Pythonic)
  • 파이썬다운 (Pythonic) 코드를 작성하려고 노력하고, API 호출을 Python의 빌트인 API 호출 형태와 유사하게 만들어라

일관성

• 네이밍: 네이밍에 일관성이 있는지 확인
  • 단어 순서: string_encode vs decode_string
  • 축약어: activate_prev vs fetch_previous, bin2hex vs strtolower
  • 언더스코어 여부: gettype vs get_class
  • 복수형: value_list vs value_list
  • 부정형: button.enabled == True vs button.disabled == True (이럴때는 긍정형으로 써야한다고 생각함)
• 빈 값: 빈 값의 의미에 일관성이 있는가? 그게 최선의 표현인가?
  • 빈 값으로 무엇을 사용할지 결정하라: None, False, [], '', 0 등
  • 예기치 않은 false 값에 주의하라: Python < 3.5 에서는 bool(datetime.time(0)) == False 가 성립
• 파라미터: 파라미터의 순서에 일관성이 있는가?
• 동작: 유사한 동작은 유사하게 표현되고 다른 동작은 다르게 표현되고 있는가? 동작의 비대칭성은 비대칭적 형태로 반영되어야 한다.

유연함

• 통합의 불연속성 줄이기
  • 클래스가 단일 책임 원칙을 지키고 있는지 확인하고, 만약 아니라면 클래스를 여러개의 클래스로 분할하라
  • 함수명에 “and”가 있거나 함수명이 여러 작엄을 수행함을 의미하고 있는지 확인하라. 만약 그렇다면 여러개의 함수로 분리하라. 다만, 이미 많은 사용자가 이를 사용하고 있다면 결합된 상태 그대로 두는게 좋다.
  • API 사용자가 어떤 동작을 번경하기 위해서 해당 코드를 복사/붙여넣기 해야하는지를 확인해보라. 코드를 복사/붙여넣기하는 대신에 후킹이나 오버라이딩 할 수 있는 메서드를 제공하라.
  • 내부 클래스 동작에 사용되는 속성(attribute)값이 get_something 메서드가 될 수 있는지 확인하라.
  • 유용하게 사용될 수 있는 파라미터는 숨기지 않는게 좋다.
  • API 사용자가 필요로 하는 것들은 모두 반환하라.
  • API 클라이언트가 코드를 호출 할 때 필요한 모든 것을 전달하라 (제어의 역전 (IoC)이 존재하는 경우)
  • API 테스트에 존재하는 모든 mock.patch를 평가해보라. 이는 런타임 중에 무언가가 유연하게 변경되기 어려움을 나타낸다. 이들을 변경할 수 있는 파라미터 지원을 고려해보라
• 추상화
  • 복수의 로부 레벨 구현체애 대한 공통적인 리소스 및 기능들을 래핑하라.
  • 가장 간단한 것부터 가장 커스터마이징 수준이 높은 것까지 다양한 추상화 레벨을 제공하라.
  • 추상화에서 빠져나올 수 있는 방법을 제공하고 추상화된 리소스 및 기능들을 직업 사용할 수 있도록 하라.
  • 다중 로우 레벨 구현제들에서 나타나는 일반적인 에러들을 하나로 래핑하고 로우 레벨 에러가 API 클라이언트에게 누출되지 않도록 하라. (어뎁터 패턴)
• 파이썬 답게 (Be Pythonic)
  • 간단한 getter`` 및setter```에는 프로퍼티를 사용하라.
  • 연산자 오버로딩에는 매직 메서드를 사용하라.
  • 간단한 디버깅에는 __repr 매직 메서드를 사용하라
  • open-close/start-end의 라이프사이클을 갖는 작업에는 with문 컨텍스트를 사용하라
  • 일반적인 동작들을 간편히 구성하거나 무언가를 등록하기 위해서는 데코레이터를 사용하라.
  • Lazy한 이터레이블 객체에는 이터레이터를 사용하라.
  • 로직을 교차시키기 위해서는 제너레이터를 사용하라.
  • 비동기 코드에는 asyncio를 사용하라.
  • 커스텀 저장소 대신 빌트인 기능들을 사용하라.
  • 간단한 제어의 역전 (IoC)를 위해 간단한 고차원 함수를 허용하라.
  • 복잡한 흐름의 경우 함수/클래스 파이프 라인, 상속, 또는 제너레이터를 순서대로 고려하라
  • 덕 타이핑과 “허가보다 용서를 구하는 것이 더 쉽다”를 존중하라.