scoon: (droid)
[personal profile] scoon
Есть такая болезнь -- недержание комментариев, оно же "комментаризм головного мозга". Страдающие от этой болезни испытывают маниакальную потребность писать никому не нужные комментарии к очевидному коду.

Сейчас, вспоминая по служебной надобности Python и освежая в памяти всяческие стилевые соглашения, перечитывал PEP-0257. Очень рекомендую к изучению как хороший пример клинической картины -- комментаризм головного мозга в терминальной стадии.

Пример "рекомендуемого" (на терминальной стандии) стиля комментирования кода.

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...


Понятно, что здоровому человеку будет достаточно вот этого:

def complex(real=0.0, imag=0.0):
    if imag == 0.0 and real == 0.0: return complex_zero
    ...


Если я знаю, что в модуле идет работа с комплексными числами (для этого достаточно прочесть однострочный docstring в начале файла), то должно быть очевидно, что метод complex(real,imag) создает комплексное число, а не соединение с LDAP-сервером, правда? Но в запущенных случаях описываемой болезни пациент не в состоянии преодолеть потребность все это документировать.

Друзья! Будьте бдительны, следите за кодом, который пишут ваши коллеги. На ранних стадиях болезнь излечима!

Date: Sunday, 27 November 2011 12:03 (UTC)
From: [identity profile] Максим Терещенко (from livejournal.com)
Заказчик понял что хочет оценивать покрытие кода комментариями. И просто счастлив когда процент покрытия стабильно растет. А программисты просто генерируют очевидные комментарии нажатием какого-нибудь хоткея и добавляя пару фраз. Получается что никто не болен?

June 2013

M T W T F S S
     12
3456789
10111213 141516
17181920212223
24252627282930

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags