3-1-4-8. Documentation

One of the key advantages of functions is that

they can help break a program down into smaller chunks.

This makes code easier to write and also easier to read because the pieces of your code,

the functions, are reusable.

If a program needs to calculate volumes of multiple cylinders,

it can call the cylinder volume function multiple times,

which is much cleaner than writing out the formula over and over again.

Functions make code easier to read because they give human readable names to processes.

While the cylinder volume formula isn’t that complicated,

it is still harder to recognize than a precisely-named function.

There is an additional technique that makes functions more readable,

documentation strings or docstrings.

Docstrings are a type of comment used to explain

the purpose of a function and how it should be used.

Here is a function for population density with a docstring.

Docstrings are surrounded by triple quotes.

The first line of the docstring is a brief explanation of the function’s purpose.

If you feel that this is sufficient documentation,

you can end the docstring here.

Single line docstrings are perfectly acceptable.

If you think that the function is complicated enough to want a longer description,

you can add a more thorough paragraph after the one-line summary.

The next element of a docstring is an explanation of the function’s arguments.

Here, you list the arguments,

state their purpose and what types the arguments should be.

Finally, it’s common to provide some description of the output of the function.

Every piece of the docstring is optional.

However, docstrings are part of good coding practice.

They assist you and future users in understanding the code you produced.

You can read a more thorough explanation of docstring conventions in the link below.

기능의 주요 장점 중 하나는

프로그램을 더 작은 덩어리로 나누는 데 도움이 될 수 있습니다.

이렇게 하면 코드를 더 쉽게 작성하고 읽기도 더 쉽게 할 수 있습니다.

기능을 재사용할 수 있습니다.

프로그램이 여러 실린더의 부피를 계산해야 하는 경우,

실린더 볼륨 함수를 여러 번 호출할 수 있습니다.

수식을 반복해서 작성하는 것보다 훨씬 깨끗합니다.

함수는 프로세스에 사람이 읽을 수 있는 이름을 부여하기 때문에 코드를 더 읽기 쉽게 만듭니다.

실린더 체적 공식은 그렇게 복잡하지 않지만,

정확히 이름이 지정된 함수보다 인식하기가 여전히 더 어렵습니다.

함수를 더 읽기 쉽게 만드는 추가 기술이 있습니다.

문서 문자열 또는 독스트링.

독스트링은 설명하는 데 사용되는 주석 유형입니다.

기능의 목적과 사용 방법.

다음은 독스트링이 있는 인구 밀도에 대한 함수입니다.

독스트링은 삼중 따옴표로 묶입니다.

독스트링의 첫 번째 줄은 함수의 목적에 대한 간략한 설명입니다.

이 문서가 충분하다고 생각되면

여기에서 독스트링을 끝낼 수 있습니다.

한 줄 독스트링은 완벽하게 허용됩니다.

더 긴 설명이 필요할 정도로 기능이 복잡하다고 생각되시면,

한 줄 요약 뒤에 더 자세한 단락을 추가할 수 있습니다.

독스트링의 다음 요소는 함수의 인수에 대한 설명입니다.

여기에서 인수를 나열합니다.

목적과 인수 유형을 명시하십시오.

마지막으로 함수의 출력에 대한 설명을 제공하는 것이 일반적입니다.

독스트링의 모든 부분은 선택 사항입니다.

그러나 독스트링은 좋은 코딩 방법의 일부입니다.

그들은 당신과 미래의 사용자들이 당신이 만든 코드를 이해하는 데 도움을 줍니다.

아래 링크에서 독스트링 규칙에 대한 더 자세한 설명을 읽을 수 있습니다.

Documentation

Documentation is used to make your code easier to understand and use. Functions are especially readable because they often use documentation strings, or docstrings. Docstrings are a type of comment used to explain the purpose of a function, and how it should be used. Here’s a function for population density with a docstring.

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

Docstrings are surrounded by triple quotes. The first line of the docstring is a brief explanation of the function’s purpose. If you feel that this is sufficient documentation you can end the docstring at this point; single line docstrings are perfectly acceptable, as in the example above.

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

    INPUT:
    population: int. The population of that 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.

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

If you think that a longer description would be appropriate for the function, you can add more information after the one-line summary. In the example above, you can see that we wrote an explanation of the function’s arguments, stating the purpose and types of each one. It’s also common to provide some description of the function’s output.

Every piece of the docstring is optional, however, docstrings are a part of good coding practice. You can read more about docstring conventions here.

%d 블로거가 이것을 좋아합니다: