Кога да пишете коментари във вашия код

На първо място, трябва да се отбележи, че винаги трябва да се опитвате да пишете документация за класове и методи. Тя обяснява за какво е необходим клас или метод и как да го използва.

RSS коментари по имейл ОК

@klay все още не сте виждали моите лайнери;)

@klay, да, еднолинейни, има някаква магия в capistrano: D

@Kostya, разсъжденията ти, че трябва да е така и че мързелът трябва да бъде преодолян, са правилни, ако ти единствен работиш по даден проект и не си разтърсен от никакви обстоятелства. В реалния живот по проекти, в които работят много хора, това не работи. По-лесно е да промените правилата, така че да са удобни за спазване и да могат да се проверяват автоматично. Например в „Perfect Code“ на Стив Макконъл всичко е добре описано и систематизирано, струва си да се използва опитът на други хора.

@ Алексей и никога не съм казвал, че седя сам на проекта. Имам ръководител на екип, правех преглед на кода, правех проект с други момчета. Ще кажа това - ако искате, тогава всичко е възможно.

О, пиша нещо с грешки) Като цяло съм бил ръководител на екипа и имам опит в изграждането на ръководства по проекти:)

По-лесно е да промените правилата, така че да е удобно да ги спазвате и те да могат да бъдат проверени автоматично.

Не преминавайте от едната крайност в другата. Твърде меки правила == няма правила. В големите системи в „реалния живот“ няма самодокументиращ се код. Само защото а) публичният API се състои от голям брой методи b) трябва да работите с повече от един API едновременно.

Под API имам предвид, включително публичния интерфейс на класовете. И може да има например методи за самодокументиране с различни имена, но в зависимост от контекста, когато два или повече класа имат еднакви имена. Седнете над доста голяма система, където някой реши, че "е по-лесно да промените правилата, така че да са удобни за спазване", ден-два и съм сигурен, че PhpDoc ще иска да напише всеки дори най-очевидният метод.

@Kostya, всичко е възможно, съгласен съм с теб. Във всеки случай здравият разум на конкретни хора е важен и правилата не са панацея. Често пъти качеството на кода зависи от личността на индивидите и веднага щом освободят контрола си, той пада. Просто имах предвид, че е важно да се вземат предвид навиците и наклонностите на хората и да се формират споразумения и правила въз основа на това. В края на краищата е по-лесно да се справите с потока, отколкото срещу)