Komentarze w kodzie #17
Description
Widzę że niektóry kwestie dotyczące komentowanie kodu się powtarzają, dlatego proponuję to opisać i ujednolicić. Moja propozycja:
Nie róbmy komentarzy jako multi-line stringów (oprócz oczywiście funkcji, method i klas).
Dobrze
1.
a = 1
# This is comment before if, it has empty line above to indicate that it start a code block.
if a == 1:
do_stuff()
a = 1
# This is very very very very very very very very very very very very very very
# long comment that explains very very very very very very very very very very
# complicated stuff.
if a == 1:
do_stuff()
Class A:
""" Comment explaining sense of existence of this class. """
def a(self):
""" This comment is for single line method/function class. """
def b(self):
"""
This comment is for multi line
method/function class.
"""
Źle
4.
a = 1
""" This comment is treated by interpreter as a string object. """
if a == 1:
do_stuff()
a = 1
""" This one
too. """
if a == 1:
do_stuff()
Class A:
# Those
def a(self):
# are
def b(self):
# bad
# too.
Umieszczajmy nad linią/blokiem kodu którego dotyczy (nie obok).
Źle
1.
a = 1 # I am short right now but i might grow much longer.
a = 1 # I am short right now but the pylint/mypy comments might appear here too.
a = 1 # I am now referring to single line but this might change someday.
Nech będą to normalnie zdania, z wielkiej litery, zakończone znakiem interpunkcyjnym.
Tu odpuszczę przykłady, ale jeżeli chodzi o przyczynę, po prostu wygląda to bardziej elegancko.
Jeżeli komentarz ma logiczną kontynuację dalej, kończmy go ... i kontynuację zaczynajmy od ....
# If the condition is met code should do this this and that ...
if True:
a()
lot()
of()
complicated()
stuff()
# ... otherwise it should do that that and this.
else:
do()
other()
stuff()