19 августа, 2012

Общее / Комментарии

Комментарии должны отвечать на вопрос почему, а код на вопрос как.

Многие считают, что потрошение кода комментариями является хорошей практикой (более того, находятся те, кто пишет об этом книги). Это заблуждение. Если ваш код невозможно понять без комментариев, то вы, скорее всего, написали плохой код.

Код должен описывать свою работу сам (self-documented), без лишней помощи в виде комментариев.

Не понятно? Давайте покажу (в листингах нижу показано не самое лучшее решение задачи, приведенное лишь для демонстрации приемуществ самодокументированного кода).

n = raw_input("Input number: ")
sum = 0
for i in range(1000):
    if i % 3 == 0 or i % 5 == 0:
        sum += i

Трудно, понять зачем нужен этот код. Давайте добавим комментарии.

n = raw_input("Input number: ")
# Getting n'th fibonacci number
sum = 0
for i in range(n):
    if i % 3 == 0 or i % 5 == 0:
        sum += i

print sum

Но теперь-то лучше? Отнюдь:

def getFibonacci(n):
  sum = 0
  for i in range(n):
      if i % 3 == 0 or i % 5 == 0:
          sum += i
  return sum

print getFibonacci(raw_input("Input number: "))

Как видите, код совершенно очевиден безо всяких комментариев.

Вы, скорее всего, сразу догадаетесь, что происходит в этой строке без каких-либо комментариев.

person.getFriends(gender="male")

Закрепим. Так делать плохо:

# iterating over friends
for a in x.getF:
  print a[0] # printing name

Так бессмысленно:

# iterating over friends
for friend in person.getFriends:
  print friend.name # printing name

А так хорошо:

for friend in person.getFriends:
  print friend.name