Muszę przyznać, że nie zgadzam się z niektórymi rzeczami zalecanymi przez inne odpowiedzi, więc zamierzam rzucić dwa centy;
Komentarze
Dokumentacja jest wyjątkowo pomocna dla nieznajomych czytających Twój kod. Zwykle wiele rzeczy nie jest wystarczająco gadatliwych, aby można je było przeczytać i zrozumieć od razu, a następnie powinieneś wyjaśnić, co robisz.
Edycja : dyskusja w sekcji komentarzy wskazała coś słusznego - nadmierne komentowanie zwykle odbywa się podczas pisania złego kodu.
Komentowanie twojej pracy powinno być precyzyjne i minimalne, ale moim zdaniem zdecydowanie powinno być obecne. Przynajmniej komentarz na każde 15 linii kodu. Na przykład nad blokami kodu dodaj wiersz o tym, co robisz:
def login(username: str, password: str, create_session: bool = True):
# Filter the user we need from the database
hash = md5(password)
users = db.table("users", db_entities.USER)
results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]
if len(results) == 0:
return None, None
else:
# Create a login session record in the database.
if create_session:
sessions = db.table("sessions", db_entities.SESSION)
ses = sessions.new()
ses.set("username", username) \
.set("expiery", 31536000 + time.time())
sessions.update(ses)
return results[0], ses
else:
return results[0], None
Minimalne komentarze wyjaśniające, dlaczego i co robisz, są bardzo pomocne w całym kodzie. Nie zgadzam się z odpowiedzią, która stwierdza
Jeśli napotkam kod zawierający komentarze, przygotowuję się na najgorsze: kod prawdopodobnie będzie zły, a szczerze mówiąc, komentarze również mogą być złe.
Wiele razy, z wdziękiem, udokumentowano dobry kod. Prawdą jest, że źli programiści widzą swoją dokumentację w stylu: „W porządku, mój kod jest zły, dodajmy kilka zdań, aby było jaśniej”.
Tak, i chociaż zdarza się to dość często, prawdą jest również, że dobrzy programiści, którzy piszą czysty kod, również chcą mieć pewność, że powrócą do swojego kodu i zrozumieją, dlaczego chcą, aby jego funkcja zachowywała się w ten sposób lub dlaczego potrzebowali tego linia, która wydaje się nieco zbędna itp.
Tak, komentarze wyjaśniające oczywiste rzeczy, niejasne komentarze, komentarze, które zostały właśnie zebrane, aby upewnić się, że „ten kod jest udokumentowany, tak, cokolwiek”, mają zapach kodu. Sprawiają, że czytanie kodu jest trudniejsze i irytujące. (Dodanie przykładu poniżej)
# Logging into Gmail when the module is imported
_client = login()
def get_client():
global _client
return _client
Przykładowe wyjaśnienie: „Cholera, Sherlock. Czy _client = login()loguje się do usługi pocztowej? OMG!”
Więcej wyjaśnień: login()metoda nie ma związku z login()metodą z powyższego przykładu.
Ale komentarze, które są zgodne ze standardami, wyjaśniają dlaczego, a nie jak, i odpowiadają na właściwe pytania , są bardzo ( bardzo ) pomocne.
Komentarze wbudowane
Jednej rzeczy NIE powinieneś (a gdybym mógł napisać to większe, zrobiłbym), jest pisanie komentarzy w tym samym wierszu kodu. To sprawia, że komentarze są bardzo specyficzne dla linii, co całkowicie pomija cel komentowania twojego kodu.
Na przykład złe komentarze w tekście:
outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail
Znacznie łatwiej byłoby odczytać i zrozumieć ten kod bez komentarzy, co czyni bałagan i nieczytelnym.
Zamiast tego komentarze w kodzie powinny znajdować się nad blokami kodu i powinny odpowiadać na ważne pytania, które mogą pojawić się podczas czytania bloku kodu.
# Constructing the email object with the values
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()
# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)
O wiele jaśniej, prawda? Teraz już wiesz, że musisz użyć login()funkcji i podać parametry send_mail()we wszystkim, czego użyłeś. Pomaga trochę, ale wciąż brakuje jednej rzeczy.
Dokumentacja funkcji
Był szeroko dyskutowany. Powinieneś zawsze poinformować czytelników, o czym jest twoja funkcja, dlaczego i co robi. Jak to robi, nie należy to do dokumentacji, ale może do przypisów funkcji.
Powinieneś jasno opisać, czego oczekujesz od swoich parametrów, a jeśli chcesz, aby zostały uzyskane / utworzone w określonej metodzie. Powinieneś zadeklarować, jaką funkcję ma zwrócić funkcja, jakie jest jej użycie itp.
Znowu taka jest moja opinia i metodologia podczas pisania mojego kodu. Nie tylko te, ale to tylko niektóre rzeczy, których nie mogłem zgodzić się z innymi odpowiedziami. No i oczywiście nie tylko komentarze odczytują twój kod, ale sam kod. Napisz czysty kod, zrozumiały i łatwy w utrzymaniu . Pomyśl o swoim własnym ja podczas kodowania ;-)