http://ibash.org.ru/quote.php?id=17217
Если Вам в программе нужно условие, то если в нём должны быть ещё несколько вложенных условий, то если без них совсем-совсем никак не обойтись, то если вам позволяет ваше время, то снабдите программу отступами и комментариями, иначе потом будет очень трудно читать такой текст, иначе сделайте это позже - когда будете посвободней, иначе минимизируйте количество условий, иначе не захламляйте код условиями, иначе обойдитесь вообще без условий.
#fbmemories
Comments (8)
Да вы, батенька, прирожденный пародист!
У меня код без комментариев ревью не пройдет. И вообще, я на Питоне пишу.
Комментарии нужны далеко не везде. Если они нужны, это уже плохой признак.
В больших проектах без документации никак. А самая лучшая документация - та, что лежит рядом с кодом. А еще лучше - прямо в нем. Т.е. - комментарии.
Не всегда все очевидно из кода. Хотя Питон - и достаточно самодокументирующийся язык.
Нет, не самая лучшая. Разве что документация по какому-нибудь наружному API: что каждая функция, параметр и поле означают. Но этого мало. Самая нужная документация в большом проекте - это обзор архитектуры и предназначения отдельных компонентов, терминология и т.п. В код такое помещать как раз неудобно. А когда ты знаешь архитектуру и терминологию, бОльшая часть кода уже понятна без дополнительных комментариев.
А вот это выносится в Readme.md
Но тут мы уже пошли по вкусовщине. Как по мне - код должен быть документирован, и комментарии - отличный способ держать и то, и другое в одном месте и плюс-минус свежим. Особенно, когда над кодом активно работают несколько человек.
Я возражаю именно против этого "код должен быть документирован, и комментарии - отличный способ держать и то, и другое в одном месте и плюс-минус свежим". Потому что это вырождается в больших компаниях в погоню за документацией (аналогично - за тотальное покрытие unit-тестами) в ущерб разработке. Отнимает драгоценное время разработчиков, снижает мотивацию, удлиняет время разработки - и ничего не даёт взамен. Много раз сталкивался с тем, что переписать запутанный код оказывалось проще, быстрее и полезнее в долгосрочной перспективе.
Не-не-не, вот чего не надо, того не надо ))
Излишества вредят всегда и везде.
Есть необходимый минимум, сверх которого - по возможности и желанию, но дохрена - так же плохо, как нихрена.
Код должен быть читабельным (т.е. самодокументирующимся). В комментарии выносятся нетривиальные вещи и/или обоснование имплементации с отступлением от best practices. Т.е. "Использую здесь такое решение, т.к. этакое приводит к ошибке такой-то там-то" - все. И нефиг разводить пособие по художественному рукоблудию там, где 10 слов по сути дела - достаточно.
Комментарии пишутся не чтобы были, а чтобы потом не ломать себе голову, почему именно так.