Коли варто писати коментарі у коді
Насамперед, слід зазначити, що документацію до класів та методів треба намагатися писати завжди. Вона розповідає, для чого взагалі потрібний клас чи метод і як його використати.
Коментарі RSS по email OK
@klay ти ще мої однорядники не бачив ;)
@klay, ага, однострочники, то в капістрано магія якась :D
Костя, ваші міркування що повинно бути так і потрібно переборювати ліньки вірні, якщо ви один працюєте на проекті і ви не похитні ні від яких обставин. У реальному житті на проектах, де працює багато людей, це не працює. Простіше правила міняти, щоб їм було зручно слідувати, і їх можна було перевірити автоматично. У Досконалом коді Стіва Макконнела, наприклад, усе добре розписано і систематезовано, варто користуватися досвідом інших людей.
@Alexey а я й не казав, що сиджу один на проекті. У мене тимлід, я займався код ревью, я робив проект з іншими хлопцями. Скажу так: якщо захотіти, то можна все.
Ох, щось я з помилками пишу) Загалом я тимлід і є досвід вибудовування гайдів за проектом :)
Простіше правила міняти, щоб їм було зручно слідувати, і їх можна було перевірити автоматично.
Від однієї крайності до іншої не йдіть. Занадто м'які правила = відсутність правил. Не буває коду, що самодокументується, у великих системах у «реальному житті». Просто тому, що а) публічний API складається з великої кількості методів; б) працювати доводиться з більш ніж одним API одночасно.
Під API я розумію, зокрема публічний інтерфейс класів. А там можуть бути, наприклад, самодокументовані методи з відмінними назвами, але залежні від контексту, коли у двох і більше класах назви збігаються. Посидіть над досить великою системою, де хтось вирішив що, «простішеправила міняти щоб їм було зручно слідувати», день-другий і я впевнений, PhpDoc захочеться писати взагалі над кожним навіть очевидним методом.
@Костя, все можна, я згоден з вами. У будь-якому випадку важливий здоровий глузд конкретних людей, і правила не панацея. Часто буває якість коду залежить від особистісних якостей окремих людей, і як тільки вони відпускають свій контроль, воно падає. Я лише мав на увазі, що важливо враховувати звички та схильності людей, і формувати угоди та правила, виходячи з цього. Адже за течією справлятись простіше, ніж проти)