morfizm (morfizm) wrote,
morfizm
morfizm

Комментарии

http://fearless-cat.livejournal.com/235261.html?thread=4171517#t4171517

Люди всерьёз считают, что писать говнокод это хорошо, потому что нужно лепить много комментариев, объясняющих говнокод, и типа так их "в заграничных университетах учат". Надо это менять. Я очень надеюсь, что те из вас, кто преподают в университетах, не учат людей писать лишние комментарии.

Привожу копию моего мнения про комментарии:

Правильно примерно так:
1. Комментарии нужны для архитектурных вещей (style guidelines, описание компонент и high level взаимодействий).
2. Комментарии (докстринги) нужны для APIs, с объяснением параметров, возвращаемых значений и побочных эффектов, в сложных случаях с примерами использования.
3. Комментарии нужны в неочевидных хаках.
4. Комментарии нужны в сложных алгоритмах.
Важно: комментарии *вредны* во всех остальных случаях.

Понятно, что 3 - нежелательно, редко и временно.
4 - вопреки распространённому мнению - встречается в жизни чрезвычайно редко. Например, если вы действительно пишите системного уровня библиотеку или ваш продукт super low latency (напр., оптимизированная 3D-игра или продукт для high frequency trading).

Плохие комментарии чаще всего ставят рядом с плохим кодом. Да, без комментариев было бы ещё менее понятно, но комментарии - неправильное решение. Правильное решение - переписать код таким образом, чтобы он был self-documenting (что чаще всего означает проще, структурнее и с хорошим покрытием юнит-тестами, служащими также в целях документации).

Почему лишние комментарии вредны:
*) Комментарии читаются в разы медленнее кода. Мысленно парсить естественный язык сложнее, чем парсить формальный.
*) В комментариях могут быть баги, ни чуть не менее опасные, чем баги в коде.
*) Баги в комментариях почти неизбежны со временем (комментарии "протухают") и от них трудно защититься - комментарии невозможно покрыть юнит-тестами.

Психологические эффекты - культура злоупотребления комментариями способствует написанию говнокода. Человек прилагает меньше усилий, чтобы код был простой, хороший и читаемый сам по себе, как бы надеясь, что комментарии компенсируют.
Tags: 1, learning, software development
Subscribe
  • Post a new comment

    Error

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 77 comments