4.15 문서화

문서화

추가 텍스트 또는 소프트웨어 코드에 포함된 설명된 정보

설명서는 코드의 복잡한 부분을 명확히 하고 코드를 더 쉽게 탐색할 수 있도록 하며 프로그램의 여러 구성 요소가 사용되는 방법과 이유를 신속하게 전달할 수 있다.

 

프로그램의 여러 레벨에 따라 다양한 유형의 설명서를 추가할 수 있다.

인라인 코멘트 - 라인 레벨

문자열 - 모듈과 기능 레벨

프로젝트 문서 - 프로젝트 레벨

 

---

인라인 코멘트

인라인 주석은 코드 전체에서 해시 기호를 따르는 텍스트다. 코드의 일부를 설명하는 데 사용되며, 향후 기여자가 작업을 이해하는 데 도움을 준다.

코멘트는 종종 복잡한 코드의 주요 단계를 문서화한다. 코멘트가 코드를 설명하면 독자는 코드를 이해하지 않아도 된다. 그러나 다른 이들은 이것이 잘못된 코드를 정당화하기 위해 주석을 사용하고 있으며, 코드에 따라 코멘트가 필요할 경우 부호(sign) 리팩터링이 필요하다고 주장한다.

코멘트는 코드가 설명되지 않는 부분을 설명하는 데 유용하다. 예를 들어, 어떤 방법이 특정한 방법으로 시행된 이면의 이력이 그것이다. 때로는 부작용이 발생하는 불명확한 외부 변수 때문에 비관습적이거나 겉으로 보기에 자의적인 접근법을 적용할 수 있다. 이런 것들은 코드로는 설명하기 어렵다.

 

---

문자열(Docstrings)

Docstring 또는 설명서 문자열은 코드에 포함된 기능 또는 모듈의 기능을 설명하는 설명서의 중요한 부분이다. 이상적으로, 각 기능에는 항상 docstring이 있어야 한다.

문서 문자열은 세 개의 따옴표로 둘러 싸여 있다. docstring의 첫 번째 줄은 함수의 용도를 간략히 설명하는 것이다.

 

One-line docstring

defpopulation_density(population, land_area):
    """Calculate the population density of an area."""
return population / land_area

기능이 더 긴 설명을 보장하기에 충분히 복잡하다고 생각될 경우 한 줄 요약 뒤에 더 자세한 문단을 추가할 수 있다.

 

Multi-line docstring

defpopulation_density(population, land_area):
    """Calculate the population density of an area.

    Args:
    population: int. The population of the area
    land_area: int or float. This function is unit-agnostic, if you pass in values in terms of square km or square miles the function will return a density in those units.

    Returns:
    population_density: population/land_area. The population density of a
    particular area.
    """
return population / land_area

docstring의 다음 요소는 함수의 인수에 대한 설명이다. 여기서는 인수를 나열하고, 인수의 목적을 진술하며, 인수의 유형을 명시한다. 마지막으로 함수의 출력에 대한 설명을 제공하는 것이 일반적이다. docstring의 모든 부분은 선택 사항이지만, doc 문자열은 바람직한 코딩 방법의 일부이다.

 

---

프로젝트 문서

프로젝트 설명서는 다른 사용자가 자신의 코드가 자신과 관련이 있는 이유와 방법, 잠재적인 프로젝트 사용자인지 또는 자신의 코드에 기여할 수 있는 개발자인지 여부를 이해시키는 데 필수적이다. 프로젝트 문서의 가장 중요한 첫 단계는 README 파일이다. 대부분의 사용자가 프로젝트와 처음 상호 작용하는 경우가 많다.

응용프로그램이든 패키지이든 프로젝트에는 README 파일이 함께 제공되어야 한다. 최소한, 이것은 그것의 기능을 설명하고, 그것의 의존성을 나열하며, 그것을 사용하는 방법에 대한 충분히 상세한 지침을 제공해야 한다. 다른 사람이 프로젝트의 목적을 이해하고 신속하게 작업을 수행할 수 있도록 최대한 단순화한다.

모든 아이디어와 생각을 종이에 정식으로 번역하는 것은 조금 어려울 수 있지만, 시간이 지날수록 더 나아질 것이고, 그렇게 하는 것은 다른 사람들이 프로젝트의 가치를 깨닫도록 돕는 데 큰 차이를 만든다. 또한 이 문서를 작성하면 설계 결정을 더 철저히 숙고해야 하므로 코드 설계를 개선하는 데 도움이 될 수 있다. 또한 미래의 기부자가 여러분의 초심을 따를 수 있도록 도와준다.