Qual é a maneira correta de comentar funções no Python?

Existe uma maneira geralmente aceita de comentar funções no Python? O seguinte é aceitável?

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

A maneira correta de fazer isso é fornecer uma sequência de caracteres. Dessa forma, help(add)também cuspirá seu comentário.

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

São três aspas duplas para abrir o comentário e outras três aspas duplas para finalizá-lo. Você também pode usar qualquer string Python válida. Não precisa ser multilinha e as aspas duplas podem ser substituídas por aspas simples.

Ver: PEP 257

Use uma sequência de caracteres, como outros já escreveram.

Você pode até dar um passo adiante e adicionar um teste de documento à sua cadeia de documentos, facilitando o teste automatizado de suas funções.

Use uma docstring :

Uma literal de cadeia de caracteres que ocorre como a primeira instrução em uma definição de módulo, função, classe ou método. Essa doutrina se torna o __doc__atributo especial desse objeto.

Todos os módulos normalmente devem ter docstrings, e todas as funções e classes exportadas por um módulo também devem ter docstrings. Métodos públicos (incluindo o __init__construtor) também devem ter documentos. Um pacote pode ser documentado na documentação do módulo do __init__.pyarquivo no diretório do pacote.

Literais de string que ocorrem em outras partes do código Python também podem atuar como documentação. Eles não são reconhecidos pelo compilador de bytecode do Python e não podem ser acessados ​​como atributos de objeto de tempo de execução (por exemplo, não atribuídos a __doc__), mas dois tipos de documentos extras podem ser extraídos pelas ferramentas de software:

1. Os literais de cadeia de caracteres que ocorrem imediatamente após uma atribuição simples no nível superior de um módulo, classe ou __init__método são chamados de "documentação de atributos".
2. Os literais de sequência que ocorrem imediatamente após outra sequência de caracteres são chamados de "colunas adicionais".

Consulte PEP 258 , "Docutils Design Specification" [2] , para obter uma descrição detalhada do atributo e de outros documentos ...

Os princípios de bons comentários são bastante subjetivos, mas aqui estão algumas diretrizes:

• Os comentários da função devem descrever a intenção de uma função, não a implementação
• Descreva quaisquer suposições que sua função faça com relação ao estado do sistema. Se ele usa variáveis ​​globais (tsk, tsk), liste-as.
• Cuidado com o excesso de arte ASCII . Ter longas sequências de hashes pode parecer facilitar a leitura dos comentários, mas pode ser irritante para lidar quando os comentários mudam
• Aproveite os recursos de linguagem que fornecem 'documentação automática', ou seja, docstrings em Python, POD em Perl e Javadoc em Java

Leia sobre o uso de docstrings no seu código Python.

De acordo com as convenções de documentação do Python :

A documentação de uma função ou método deve resumir seu comportamento e documentar seus argumentos, valor (es) de retorno, efeitos colaterais, exceções levantadas e restrições sobre quando ela pode ser chamada (todas, se aplicável). Argumentos opcionais devem ser indicados. Deve ser documentado se os argumentos da palavra-chave fazem parte da interface.

Não haverá regra de ouro, mas forneça comentários que signifiquem algo para os outros desenvolvedores da sua equipe (se você tiver uma) ou mesmo para si mesmo quando voltar a ela seis meses depois.

Eu recomendaria uma prática de documentação que se integre a uma ferramenta de documentação como o Sphinx .

O primeiro passo é usar um docstring:

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

Eu daria um passo além do que apenas dizer "use um docstring". Escolha uma ferramenta de geração de documentação, como pydoc ou epydoc (eu uso o epydoc no pyparsing) e use a sintaxe de marcação reconhecida por essa ferramenta. Execute essa ferramenta frequentemente enquanto estiver desenvolvendo, para identificar falhas na documentação. De fato, você pode até se beneficiar escrevendo as instruções para os membros de uma classe antes de implementá-la.

Use documentos .

Esta é a convenção sugerida interna no PyCharm para comentários de descrição de função:

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

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

Embora eu concorde que isso não deva ser um comentário, mas uma doutrina, como sugerem a maioria das respostas (todas?), Desejo adicionar numpydoc (um guia de estilo de doutrina ) .

Se você fizer assim, poderá (1) gerar automaticamente a documentação e (2) as pessoas reconhecerem isso e terão mais facilidade para ler seu código.

Você pode usar três aspas para fazer isso.

Você pode usar aspas simples:

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

Ou aspas duplas:

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