[클린코드] Docstring과 어노테이션

문서화

코드의 구조를 알려주기 위한 과정. 규모가 커질수록 중요성이 늘어난다.

1. 문서화는 주석의 추가와 다르다

2. 주석을 가급적 피해야한다.

3. 문서화를 통해 데이터타입 설명, 예제 제공이 가능하다.

Docstring

소스코드에 포함된 문서.

1. 기본적으로 리터럴 문자열

2. 로직의 일부분 문서화를 위해 코드에 배치

3. 코멘트가 아니라 문서다

4. 코드에 주석을 다는 것은 나쁜 습관이다. 아이디어를 제대로 표현하지 못했다는 말

5. docstring은 코드의 컴포넌트(모듈,클래스,함수등)에 대한 문서화다

6. docstring은 많이 추가하는 것이 좋다.

dict.update?? 명령어

docstring을 확인하기 위한 명령어

1. dict.update 메서드의 docstring이 출력

2. 키워드 인자에 전달된 값으로 dict 업데이트

함수에서의 Docstring

말그대로 함수내에서 docstring을 작성하고 확인하는 방법

1. 객체에 docstring이 정의되어 있으면 __doc__ 속성으로 접근가능하다.

2. 클래스 선언 후 내부 바로 아랫줄에 큰따옴표 3개나 작은따옴표 3개로 작성하자

Sphinx(스핑크스)

문서화를 위한 일종의 도구.

1. Sphinx를 실행하면 프로젝트 문서화를 위한 골격을 만들어준다.

2. autodoc 익스텐션 (sphinx.ext.autodoc) 을 이용하면 코드의 docstring으로 문서화된 페이지를 만들어준다.

Docstring 유의점

작성하는데 번거롭지만 꼭 필요한 과정이라고 볼 수 있다.

1. 문서와 프로젝트가 하나가 되도록 도구를 오픈해야한다.

2. 모든 팀원이 문서화에 참여할 수 있어야한다.

3. docstring의 단점은 지속적으로 수작업을 해야한다는 것, 정말 유용하게 사용되려면 여러줄에 걸쳐 상세하게 적어야하는 것

4. 코드를 변경할 때 위키, 사용자매뉴얼, README파일 또는 docstring에 관한 내용을 업데이트해야한다.

어노테이션

타입과 같은 메타데이터에 대한 힌트를 주는 것

1. 파이썬은 동적으로 타입이 결정되기에 변수나 객체의 값을 알기 힘들다

2. 이를 어노테이션으로 명시해주어야함

3. Mypy와 같은 도우고 타입 힌트 등의 자동화된 검증도 할 수 있다.

4. PEP-3107에서 어노테이션이 소개된다.

5. 사용자에게 함수인자로 어떤 값이 와야하는지 힌트를 주는 것

6. 어노테이션으로 변수의 예상 타입을 지정 (타입만이 아니라 변수 이해를 위한 메타데이터 전부 가능)

7. 대신 파이썬이 타입을 검사하거나 강제하지는 않는다

파이썬에서 ->

리턴값 형식을 알려준다. 말그대로 명시만 해준다.

1. 파이썬의 리턴값을 명시해준다

2. -> str 이라면 str의 리턴을 가진다는 것을 명시해주는 것

__anotations__ 속성

클래스에 할당되는 값과 같은 정보를 알 수 있게 만드는 속성.

1. 어노테이션으로 생기는 속성

2. 어노테이션의 이름과 값을 매핑한 dict의 값

3. 문서 생성, 유효성 검증, 타입체크가 가능하다.

어노테이션 개선사항

버전이 업데이트되면서 어노테이션에 대한 방식이 추가되기 시작했다.

1. 파이썬 3.5부터 typing 모듈이 스탠다드 라이브러리에 추가되어 내장자료구조(list,dict등)에 대한 어노테이션 추가가 가능하다

2. 파이썬 3.6부터 변수에 직접 주석을 달 수 있다. (값을 지정하지 않은 채로 변수의 타입 선언이 가능하다)

Docstring vs 어노테이션

어노테이션으로 설명을 하고 그에 대한 보충설명은 Docstring으로 진행하는 느낌이다.

1. 서로 보완적인 개념이다.

2. doctstring의 정보 중 일부는 어노테이션으로 이동가능하다. 하지만 docstring으로 더 나은 문서화의 여지를 남겨두어야한다.

3. 예를 들어 함수의 예외처리를 진행할때 제대로 진행되었을 때의 진행사항은 어노테이션으로 알 수 없다.

4. 이럴 때 보완해주는 것이 docstring. 입력값,반환값,예상형태를 더 잘 이해할 수 있다. 단위테스트에서도 유용하게 사용가능하다.