Я скачал фреймворк, а там у каждой функции есть комментарии. Да еще и очень подробные (PHPDoc). Должен ли я также писать свои сайты?

Question

[sorry_i_noob]

Неужели я также должен писать свой код? И каждую функцию подробно комментировать PHPDoc'ми? Или это только если я пишу что-то такое, что будут массово использовать другие люди? Какую-нибудь либу / фреймворк.

Comments

[Кирилл Несмеянов]

PHPDoc пишется одной кнопкой в любой современной IDE, так что не представляет из себя чего-то "за гранью"

[sorry_i_noob]

Кирилл Несмеянов, одной кнопкой просто копируется в комментарии сигнатура метода, возвращаемое значение и исключения. А вот описывать все это - другое дело.

[Кирилл Несмеянов]

sorry_i_noob, ну да. Документация по публичным методам уже потом, да.

[Дмитрий]

Да, надо использовать комментарии, phpdoc.
И в первую очередь не для кого-то, а для себя, чтобы по прошествии времени Вы могли сами разобраться в своём коде.
Со временем забывается для чего написан тот или иной метод или ещё что-то. Вот чтобы уходило меньше времени на то, чтобы вспомнить и пишут комментарии.

Answer 1

[entermix]

Вы никому ничего не должны.

Comments

[sorry_i_noob]

Я про то, чтобы стать хорошим программистом. Про best practice. Для этого я должен писать код (и комментарии к нему) по каким-то правилам. А не просто как попало.

Answer 2

[Илья Белобородов]

Стремись писать так, что бы было все ясно без комментариев

Если работаешь на себя и не хочешь потерять клиента, то пиши код, что бы никто кроме тебя не разобрался.

такой себе совет. в любом коде можно разобраться

Comments

[Олег]

Не спорю, но усложнить жизнь можно)

Answer 3

[Олег]

Если работаешь на себя и не хочешь потерять клиента, то пиши код, что бы никто кроме тебя не разобрался.
При работе на дядю - приходится придерживаться стандартов. Что бы дядя расставить с тобой нашёл замену

Comments

[Lander]

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

[Decadal]

Вы наверное и исходники php обфусцируете?

[Олег]

Lander, у каждого свое мнение.
Почему я должен делать работу для Васи?
А насчёт клиентов - всегда вилка сьезжает. И лучше уменьшить риск потерять клиента, не из-за 'плохой работы', а потому что Вася предлагает услуги дешевле

[Decadal]

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

[Олег]

Decadal, вы о двух концах палки.
Заказчику вы продаёте функционал, но никак не код.
И про втирание Заказчику о коде, как о произведении искусства-не более чем очковтирательство приёма маркетинга

[Decadal]

Олег, вы передаете права на интеллектуальную собственность всего, что делаете по заказу, если не оговорено иначе. Это основа всех трудовых договоров, договоров о подряде и субподряде. Код принадлежит заказчику.

[Олег]

Decadal, Я уже писал. Когда на дядю х@рачишь - то используется стандарт.
Дядей все чаще выступают очковтиратили, которые и к крограммированию отношения не имеют, но умеют ̶п̶р̶о̶д̶а̶в̶а̶т̶ь̶ втюхивать.
Конечному заказчику нужно что бы работало по его хотелкам.
А кучу процедурного говнокода, какими комментариями не оборачивай - он говнокодом по своей сути и останется
Взять тот же БЭМ нах плодить эти строки, которые решаются написанием всего одного класса, к примеру?
Это убожество внутренних стандартов изначально подразумевает текучку разработчиков.
Даже в этой ситуации суть моего ответа. Вася потом просто пользуется готовым решением, них не напрягавшись