Чи більше коментарів краще в умовах високого обороту?

Я сьогодні спілкувався з колегою. Ми працюємо над кодом для двох різних проектів. У моєму випадку я єдина людина, яка працює над своїм кодом; в її випадку кілька людей працюють над однією кодовою базою, включаючи студентів кооперативів, які приходять і ходять досить регулярно (між кожні 8-12 місяців). Вона сказала, що вона є ліберальною зі своїми коментарями, виставляючи їх всюди. Її міркування полягають у тому, що це допомагає їй пам’ятати, де такі речі і що роблять, оскільки велика частина коду не була написана нею, і її міг змінити хтось, крім неї. Тим часом я намагаюся мінімізувати коментарі до свого коду, розміщуючи їх лише в місцях, де немає очевидного вирішення чи помилки. Однак я в цілому краще розумію свій код і маю більш прямий контроль над ним.

На мою думку, коментарі повинні бути мінімальними, і код повинен розповідати більшу частину історії, але її міркування теж мають сенс. Чи є якісь вади в її міркуваннях? Він може захаращувати код, але в кінцевому підсумку це може бути дуже корисним, якщо над ним працює багато людей у ​​коротко- та середньостроковій перспективі.

Коментарі не захаращують код.

І коли вони це роблять, добре, що кожна половина гідної IDE може приховати / скласти коментарі. В ідеалі історію слід розповідати за допомогою коду, документа з вимогами, історії виконання зобов’язань та тестів, а не коментарями. Однак надмірне коментування може зашкодити лише тоді, коли коментарі зосереджені на тому, як, а не чому, однак це інша дискусія .

Я думаю, що і ви, і ваш колега ви "праві", різниця полягає, звичайно, у тому, що ви працюєте одна і вона в команді, до якої часто входять недосвідчені розробники. У вас не стільки інша філософія щодо коментарів, скільки абсолютно різні вимоги щодо передачі коду. Аргумент "це мені допомагає запам'ятати" також може випливати з того, що вона має справу з набагато більшим кодом, ніж ти, і, що ще важливіше, кодом, створеним різними людьми, кожен з яких має свої особисті переваги та примхи.

Зрештою, кодові коментарі, хоча і очевидні вади, - це найпростіший і швидкий спосіб передачі коду. Залежно від складу команди та організації, це може бути єдиний спосіб, який стосується найменшого загального знаменника. Я, як правило, дотримуюся вашої філософії коментування, коли працюю в самоті та підлаштовується під колегу під час роботи в команді, особливо, якщо це розумна незбалансована навичка команди.

Широкі коментарі в такому середовищі прикривають проблему, яку слід вирішити іншим способом.

Якісний, читабельний код ніколи не потребує додаткових коментарів для пояснення того, що він робить. Єдиний час коментувати - це коли ти хочеш пояснити, чому щось було зроблено певним чином. І навіть тоді ці коментарі, можливо, можуть бути в повідомленнях про здійснення джерела.

Отже, проблема, яку вона вирішує, полягає в тому, що їй доводиться працювати зі студентами, які не знають, як написати свій код читабельним чином. На мою думку, захаращування коду коментарями є слабким рішенням цієї проблеми.

Суворі огляди коду були б набагато ефективнішими, як у догляді за кодом, так і в покращенні студентів на майбутнє, будь то в одній компанії чи деінде.

Проблема з коментарями полягає в тому, що вони, як правило, швидко переростають з кодом. Це означає, що в коді часто є оманливі або виправдані неправильні коментарі, тому вони шкодять читабельності більше, ніж допомагають.

Мета полягає в тому, щоб зробити кодову базу легкою для розуміння та зміни. Ви можете це зробити, хоч ліберальне використання коментарів (хоча ви можете зіткнутися з проблемою поза коментарями даних) або ви можете написати код самодокументування (наскільки це можливо) і використовувати лише коментарі для пояснення нетривіального "чому "запитання. Будь-який підхід може спрацювати, але майте на увазі, що для зміни коду вам доведеться зрозуміти сам код, а не лише коментарі. Тому, хоча коментарі можуть допомогти вам зрозуміти код, в кінці дня вам все-таки доведеться зрозуміти сам код. З огляду на це, я віддаю перевагу підходу до кодування, що самодокументується. Здається, це більш прямий спосіб створити чисту кодову базу.

"Чи більше коментарів краще в умовах високого обороту?"

Я думаю, що вони можуть бути гіршими:

• Різні автори використовуватимуть різні стилі та рівні деталей і будуть менше оновлювати коментарі інших людей.

• Думка "Що потрібно коментувати" змінюється від людини до людини.

• Вони продовжують практику написання коду, який важко читати з коментарями, щоб пояснити його на відміну від простого для читання коду з описовими іменами.

• Підтримання їх формату та послідовності стає роботою саме по собі.

• Нові користувачі повинні засвоїти стандарт "формату", перш ніж зможуть вносити швидкі зміни.

Пункт 1: Чіткість є важливою у високооборотних умовах

Пункт 2: Багатослівність - це не ясність

Додавання коментарів до коду може або не покращить чіткість; це залежить від доданих вами коментарів. І як тільки буде досягнуто оптимальної ясності, додаткові коментарі погіршать ситуацію, а не краще.

Хоча коментарі є складовою ясності, якість коду є значно важливішим компонентом. Розумність - це протилежність ясності . Якщо функція коду не очевидна відразу через випадкове читання, код не особливо чіткий, а коментарі (незалежно від того, наскільки якісні коментарі є) є поганою та неефективною заміною чіткого коду.

Наприклад, заповнення прапора у високому біті незв'язаного поля може бути дозволено в певних обставинах, і це може спричинити навантаження з точки зору продуктивності в певних обставинах, але це, як правило, завжди погана ідея щодо чіткості , навіть якщо ви прокоментуєте чорт із цього.

Якщо вам доведеться пояснювати в прозовій справі, що робить ваш код, то врахуйте будь-що з наступного: Зауважте, що деякі з них можуть вплинути на продуктивність, але продуктивність може бути не такою важливою, як ясність у певних випадках.

• Кращі імена змінних та імена функцій
• Краще компонування коду та інтервал
• Видаліть будь-які «хитрощі», які ви вважали гарною ідеєю
• Груповий код відповідно до концептуальної функції (наприклад, витяг коду для певної мети у відповідну функцію, навіть якщо ви викликаєте її лише один раз)
• Використовуйте більш прямий алгоритм (умови дозволяють)
• Використовуйте відомі бібліотеки для загальної функціональності

Попрощена відповідь: "Чим більше шансів перечитати ваш код, тим вище буде тягар пояснення того, що ви робите". Це може бути, полегшивши читання коду, прокоментувавши його, створивши офіційну документацію, дотримуючись стандартів стилів ... Зауважте, що саме ви можете переробляти пізніше, хоча це, безумовно, стосується й інших у середовище високої оборотності.

Є ще одна чудова нитка, яка висвітлює, чи є коментарі документацією чи ні.

Коментарі в деяких сценаріях корисніші, ніж в інших. Це настільки фундаментально, що я переживаю, як пояснити це посеред стільки відповідей, які я вважаю "антикоментуванням".

Якщо ваш код може не читатися роками, коментарі важливіші, ніж якщо у вас часті переробки коду, чітке володіння кодом та рясні огляди коду. Якщо ваша заявка є складною і використовує методи, які не відразу очевидні для спостерігача, що володіє цією мовою, коментарі важливіші, ніж якщо система є прославленим "Hello World". Якщо база коду не настільки сувора зі стандартами, як це могло б, коментарі важливіші, ніж якщо ви працюєте з шести шарами якості. Якщо ви працюєте в команді з восьми людей, які просто вивчають мову, коментарі важливіші, ніж якщо у вашій команді є вісім програмних програм Pulitzers. Якщо у вас на колінах потрапила розсипана програма,коментарі важливіші, ніж якби ви змогли створити це чисто з нуля.

Чи було б краще в більшості таких сценаріїв виправити основну причину, а не збільшувати використання коментарів? Абсолютно. Але іноді ви застрягаєте з кодовою базою, на якій є більше відбитків пальців, ніж міський смартфон, і найкращий спосіб її покращити - це зробити ваші зміни максимально читабельними і прокоментувати виклик з неї.

До вашої конкретної проблеми: коментарі не повинні надходити стільки, щоб захаращувати код. Добре написаний абзац у верхній частині підпрограми, що описує, чому функція існує, і, можливо, вона використовує такий підхід, часто є найкращою ставкою для того, щоб допомогти наступному програмісту отримати своє значення.