Jaki jest właściwy sposób komentowania funkcji w Pythonie?

Czy istnieje ogólnie przyjęty sposób komentowania funkcji w Pythonie? Czy poniższe są dopuszczalne?

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

Prawidłowym sposobem na to jest dostarczenie dokumentów. W ten sposób help(add)wypluje również Twój komentarz.

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

To trzy podwójne cudzysłowy, aby otworzyć komentarz i kolejne trzy podwójne cudzysłowy, aby go zakończyć. Możesz także użyć dowolnego prawidłowego ciągu znaków Pythona. Nie musi być wielowierszowy, a podwójne cudzysłowy można zastąpić pojedynczymi cudzysłowami.

Patrz: PEP 257

Użyj sznurka, tak jak inni już napisali.

Możesz nawet pójść o krok dalej i dodać doctest do swojego dokumentu, dzięki czemu automatyczne testowanie funkcji jest bardzo proste.

Użyj docstringu :

Literał łańcuchowy występujący jako pierwsza instrukcja w definicji modułu, funkcji, klasy lub metody. Taki ciąg dokumentów staje się __doc__specjalnym atrybutem tego obiektu.

Wszystkie moduły powinny normalnie mieć ciągi dokumentacyjne, a wszystkie funkcje i klasy eksportowane przez moduł powinny również mieć ciągi dokumentacyjne. Metody publiczne (w tym __init__konstruktor) również powinny mieć ciągi dokumentacyjne. Pakiet można udokumentować w dokumentacji modułu __init__.pypliku w katalogu pakietu.

Literały łańcuchowe występujące w innym miejscu kodu Pythona mogą również służyć jako dokumentacja. Nie są rozpoznawane przez kompilator kodu bajtowego Pythona i nie są dostępne jako atrybuty obiektów środowiska wykonawczego (tj. Nie są do nich przypisane __doc__), ale narzędzia programowe mogą wyodrębnić dwa typy dodatkowych ciągów dokumentów:

1. Literały łańcuchowe występujące bezpośrednio po prostym przypisaniu na najwyższym poziomie modułu, klasy lub __init__metody nazywane są „ciągami dokumentów atrybutów”.
2. Literały tekstowe występujące bezpośrednio po innym łańcuchu dokumentów nazywane są „dodatkowymi ciągami dokumentacyjnymi”.

Szczegółowy opis atrybutu i dodatkowe dokumenty można znaleźć w PEP 258 , „Specyfikacja projektu Docutils” [2].

Zasady dobrego komentowania są dość subiektywne, ale oto kilka wskazówek:

• Komentarze funkcyjne powinny opisywać zamiar z funkcji, a nie realizacji
• Przedstaw wszelkie założenia, które twoja funkcja przyjmuje w odniesieniu do stanu systemu. Jeśli używa jakichkolwiek zmiennych globalnych (tsk, tsk), wymień je.
• Uważaj na nadmierną grafikę ASCII . Może się wydawać, że posiadanie długich ciągów skrótów sprawia, że ​​komentarze są bardziej czytelne, ale mogą być irytujące, gdy się zmieniają
• Skorzystaj z funkcji językowych, które zapewniają „automatyczną dokumentację”, tj. Ciągi dokumentacyjne w Pythonie, POD w Perlu i Javadoc w Javie

Przeczytaj o używaniu ciągów dokumentów w kodzie Pythona.

Zgodnie z konwencjami docstringowymi Pythona :

Dokumentacja funkcji lub metody powinna podsumować jej zachowanie i udokumentować jej argumenty, zwracane wartości, skutki uboczne, zgłoszone wyjątki i ograniczenia dotyczące tego, kiedy można ją wywołać (wszystkie, jeśli mają zastosowanie). Należy wskazać argumenty opcjonalne. Należy udokumentować, czy argumenty słów kluczowych są częścią interfejsu.

Nie będzie złotej zasady, ale raczej dawaj komentarze, które znaczą coś dla innych programistów w Twoim zespole (jeśli takiego masz) lub nawet dla siebie, gdy wrócisz do tego sześć miesięcy później.

Wybrałbym praktykę dokumentacji, która integruje się z narzędziem dokumentacyjnym, takim jak Sphinx .

Pierwszym krokiem jest użycie docstring:

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

Poszedłbym o krok dalej niż tylko powiedzenie „użyj sznurka dokumentacyjnego”. Wybierz narzędzie do generowania dokumentacji, takie jak pydoc lub epydoc (używam epydoc w pyparsingu) i używaj składni znaczników rozpoznawanej przez to narzędzie. Uruchamiaj to narzędzie często podczas programowania, aby zidentyfikować dziury w dokumentacji. W rzeczywistości możesz nawet skorzystać na napisaniu dokumentacji dla członków klasy przed jej zaimplementowaniem.

Stosować docstrings .

Oto wbudowana zalecana konwencja w PyCharm dla komentarzy do opisu funkcji:

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

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

Chociaż zgadzam się, że nie powinien to być komentarz, ale dokument, jak sugeruje większość (wszystkich?) Odpowiedzi, chcę dodać numpydoc (przewodnik po stylu dokumentów) .

Jeśli zrobisz to w ten sposób, możesz (1) automatycznie wygenerować dokumentację i (2) ludzie to rozpoznają i będą mieć łatwiejszy czas na odczytanie kodu.

Aby to zrobić, możesz użyć trzech cudzysłowów.

Możesz używać pojedynczych cudzysłowów:

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

Lub podwójne cudzysłowy:

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