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

Друзья! Будьте бдительны, следите за кодом, который пишут ваши коллеги. На ранних стадиях болезнь излечима!
From:
Anonymous( )Anonymous This account has disabled anonymous posting.
OpenID( )OpenID You can comment on this post while signed in with an account from many other sites, once you have confirmed your email address. Sign in using OpenID.
User
Account name:
Password:
If you don't have an account you can create one now.
Subject:
HTML doesn't work in the subject.

Message:

 
Notice: This account is set to log the IP addresses of everyone who comments.
Links will be displayed as unclickable URLs to help prevent spam.

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