Python에서 함수를 코멘트하는 적절한 방법은 무엇입니까?

Python에서 함수를 코멘트하는 적절한 방법은 무엇입니까?

일반적으로 Python에서 기능을 코멘트하는 방법이 있습니까?다음 사항으로 괜찮으시겠습니까?

#########################################################
# Create a new user
#########################################################
def add(self):

올바른 방법은 문서 문자열을 제공하는 것입니다. 하면, ㅇㅇㅇㅇㅇ는,help(add)댓글도 뱉을 거예요.

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

코멘트를 오픈하기 위한 큰따옴표 3개와 종료하기 위한 큰따옴표 3개가 있습니다.유효한 Python 문자열을 사용할 수도 있습니다.여러 줄일 필요는 없으며 큰 따옴표는 작은 따옴표로 대체할 수 있습니다.

참조: PEP 257

docstring을 사용합니다.

이것은 PyCharm에 내장된 권장 규약으로 docstring 코멘트를 사용하여 함수를 기술합니다.

def test_function(p1, p2, p3):
    """
    test_function does blah blah blah.

    :param p1: describe about parameter p1
    :param p2: describe about parameter p2
    :param p3: describe about parameter p3
    :return: describe what it returns
    """ 
    pass

다른 사용자가 이미 썼듯이 docstring을 사용합니다.

한 걸음 더 나아가 doctest를 문서 문자열에 추가할 수도 있습니다.이것에 의해, 기능의 자동 테스트가 간단하게 실현됩니다.

docstring을 사용합니다.

모듈, 함수, 클래스 또는 메서드 정의에서 첫 번째 문장으로 발생하는 문자열 리터럴.은 'Docstring'이 됩니다.__doc__★★★★★★★★★★★★★★★★★★★★★★★★★★★

일반적으로 모든 모듈에는 docstring이 있어야 하며 모듈에서 내보내는 모든 기능 및 클래스에도 docstring이 있어야 합니다.메서드(「」를 한다)__init__문서 문자열는 "" 의 docstring에 .__init__.py이치노

Python 코드의 다른 곳에서 발생하는 문자열 리터럴도 문서 역할을 할 수 있습니다.되지 않으며 속성으로 수 "Python"이 "Python"에 않습니다).__doc__툴에 두 의 추가 될 수 즉, 소프트웨어 툴은 다음과 같습니다.

1. ""의 하는 문자열 __init__문서 스트링
2. 다른 문서 문자열 직후에 발생하는 문자열 리터럴을 "추가 문서 문자열"이라고 합니다.

속성 및 추가 문서 문자열에 대한 자세한 내용은 PEP 258 , "Docutils Design Specification" [2]를 참조하십시오.

좋은 코멘트의 원칙은 상당히 주관적이지만, 다음은 몇 가지 가이드라인을 제시하겠습니다.

• 기능 코멘트는 구현이 아닌 기능의 의도를 기술해야 한다.
• 시스템 상태에 관한 기능상의 전제 조건을 개략적으로 설명합니다.글로벌 변수(tsk, tsk)를 사용하는 경우 해당 변수를 나열합니다.
• 과도한 ASCII 아트를 주의해 주세요.해시 문자열이 길면 코멘트가 읽기 쉬워 보일 수 있지만 코멘트가 바뀌면 대처하기가 귀찮을 수 있습니다.
• Python, Perl의 POD, Java의 Javadoc과 같은 '자동 문서'를 제공하는 언어 기능을 활용하십시오.

Python 코드에서 docstring 사용에 대해 읽어보십시오.

Python docstring 규칙에 따르면:

함수 또는 메서드의 docstring은 해당 동작을 요약하고 해당 인수, 반환값, 부작용, 발생한 예외 및 호출할 수 있는 시기에 대한 제한사항을 문서화해야 합니다(해당하는 경우 모두).옵션 인수를 지정해야 합니다.키워드 인수가 인터페이스의 일부인지 여부를 문서화해야 합니다.

금칙은 없지만 팀의 다른 개발자(있는 경우)에게 의미 있는 코멘트를 제공하거나 6개월 후에 복귀할 때 자신에게 의미 있는 코멘트를 제공합니다.

스핑크스와 같은 문서 작성 도구와 통합되는 문서 작성 연습을 하고 싶습니다.

첫 번째 순서는,docstring:

def add(self):
 """ Method which adds stuff
 """

나는 단지 "의사 문자열을 사용한다"는 말보다 한 걸음 더 나아가고 싶다.pydoc 나 epydoc (나는 pyparsing에서 epydoc을 사용한다)와 같은 문서 생성 도구를 선택하고 해당 도구가 인식하는 마크업 구문을 사용합니다.개발 중에는 문서의 결함을 식별하기 위해 이 도구를 자주 실행하십시오.실제로 클래스를 구현하기 전에 클래스 구성원을 위한 문서 문자열을 작성하는 것이 도움이 될 수도 있습니다.

코멘트가 아니라 대부분의 답변에서 알 수 있듯이 문서 문자열이어야 한다는 것에 동의하지만 numpydoc(문서 문자열 스타일 가이드)을 추가하고 싶습니다.

이렇게 하면 (1) 문서를 자동으로 생성하고 (2) 사용자가 이를 인식하여 코드를 쉽게 읽을 수 있습니다.

따옴표 세 개를 사용해서 할 수 있어요.

작은 따옴표를 사용할 수 있습니다.

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

또는 큰따옴표:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """

올바른 방법은 다음과 같습니다.

def search_phone_state(phone_number_start,state,dataframe_path,separator):  
   """
   returns records whose phone numbers begin with a phone_number_start and are from state
   """
   dataframe = pd.read_csv(filepath_or_buffer=dataframe_path, sep=separator, header=0)
   return dataframe[(pd.Series(dataframe["Phone"].values.tolist()).str.startswith(phone_number_start, na="False"))& (dataframe["State"]==state)]

필요한 경우:

help(search_phone_state)

다음과 같이 출력됩니다.

Help on function search_phone_state in module __main__:

search_phone_state(phone_number_start, state, dataframe_path, separator)
returns records whose phone numbers begin with a phone_number_start and are from state

언급URL : https://stackoverflow.com/questions/2357230/what-is-the-proper-way-to-comment-functions-in-python