scoon_the_crazy (scoon_the_crazy) wrote,
scoon_the_crazy
scoon_the_crazy

Category:

Комментаризм головного мозга

Есть такая болезнь -- недержание комментариев, оно же "комментаризм головного мозга". Страдающие от этой болезни испытывают маниакальную потребность писать никому не нужные комментарии к очевидному коду.

Сейчас, вспоминая по служебной надобности 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-сервером, правда? Но в запущенных случаях описываемой болезни пациент не в состоянии преодолеть потребность все это документировать.

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

  • Отпуск

    В понедельник сажусь в поезд и впервые за последние 3 (4?) года еду домой в отпуск. Соответственно, кому буду нужен -- будет 2 недели на то, чтобы…

  • Адовые клиенты?

    Почитываю " Адовых клиентов". Авторы считают это юмором. Тем не менее, очень многое из этих "перлов" нужно рассматривать всерьез как руководство к…

  • Programming Languages, первая неделя

    Закончилась (с открытием Peer Assessments по первому домашнему заданию) первая неделя курса Programming Languages. Текущая оценка качества курса: 9…

  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your IP address will be recorded 

  • 1 comment