Блоґ одного кібера

Історія хвороби контуженого інформаційним вибухом

Легенда про самодокументований код

with 12 comments

Якось був код:

        if self.get_package_ids() == [None]: # only free package

Він був дещо незрозумілим, тому прокоментованим. Але потім в когось з’явилась ідея додати

    def only_free_package(self):
        return self.get_package_ids() == [None]

І коментар в нашому рядочку став зайвим:

        if self.only_free_package():

Ось і все. Це коротка легенда з простим сюжетом. Її мораль – методи призначені не тільки для повторного використання. Їх також варто використовувати для ізоляції рівнів абстракції. Мартін Фаулер називає це extractMethod.

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

Але дуже часто я бачив псевдокод нижчого рівня ніж Python. Я читав погані псевдокоди?

Advertisements

Written by bunyk

Травень 14, 2012 at 14:25

Оприлюднено в Кодерство

Tagged with , ,

Відповідей: 12

Subscribe to comments with RSS.

  1. Дуже гарне спостереження. Я давно стверджую, що коментарі потрібні лише там, де бракує виразності основного синтаксису.

    Максим Іванов

    Травень 14, 2012 at 22:13

  2. хм, стало більше коду, більше функцій, а зрозумілість не змінилась. У чому профіт?

    danbst

    Травень 15, 2012 at 07:57

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

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

      bunyk

      Травень 16, 2012 at 22:26

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

      >>> тому часто при читанні коду коментарі можна опускати одразу
      ну, програма – це не художній твір, не потрібно пхати все у first class.

      >>> голова того хто читає функцію вищого рівня, не перегружається зайвими деталями реалізації
      тут уже залежить від мислення читаючого, імхо це занадто сильне спрощення. я б зробив інакше – визначив free_package = [None] і потім робив би перевірку

      if self.get_package_ids() == free_package:

      це також зменшує деталі реалізації, залишає виразність коду і не створює лишню функцію-абстракцію.

      danbst

      Травень 17, 2012 at 00:08

      • Ти прискіпуєшся до несуттєвих деталей. Основна ідея, як на мене, в тому, що коли по коду не зрозуміло одразу, що він робить — може бути гарною ідеєю його переписати так, щоб він став зрозумілим. І що в такому випадку коментарі, які пояснюють, що ж саме робить код, стають непотрібними.

        Max Ulidtko

        Травень 17, 2012 at 00:21

    • Щойно подумав що можу пояснити краще. Якщо нам в іншому місці доведеться перевірити що пакет безплатний у випадку виклику методу ми так і зробимо. Якщо методу нема – коментар доведеться написати вдруге. А два однакові коментарі – це ще гірше ніж два однакові фрагменти коду. Виділення методу попереджує як одне так і інше. І хоча всі кажуть що не варто вгадувати на перед що нам в майбутньому знадобиться, а що ні – створення методу – це штука яка часто необхідна прямо зараз. Не заради уникнення повторення, а заради абстрагування.

      bunyk

      Червень 17, 2013 at 13:52

      • насправді я вже давно прийняв думку Max Ulidtko. Коментарі не потрібні, якщо код ясний, бо коментарі рідко хто підтримує в актуальному стані (на відміну від коду), ну і твій приклад – коментарі погано вписуються у “програмну” модель.

        danbst

        Червень 17, 2013 at 14:13

  3. Ще згадалася доктрина literate programming, яка іде в діаметрально протилежному напрямку, роблячи написання коментарів легшим та пріорітетнішим за написання власне програмного коду.

    Заснована Дональдом Кнутом і досі підтримується певними мовами програмування (скажімо, я бачив найсправжнісінький код на Хаскелі у файлах .lhs із відповідним «literate haskell» синтаксисом).

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

    Max Ulidtko

    Травень 17, 2012 at 00:34

  4. Ще добрий шматок цієї (нескладної) дискусії покритий тут http://programmers.stackexchange.com/q/201657/49834

    Max Ulidtko

    Червень 17, 2013 at 14:25

    • О, дякую за посилання. Мені якраз знадобиться для планованої статті про те як читати код. (Яку я пишу можливо тому що не хочу його читати. І не тільки тому що там коментарів нема. Аааа!) 😀

      bunyk

      Червень 17, 2013 at 14:34

  5. […] Рефакторинг. Наприклад дайте нормальні імена ідентифікаторам, кілька разів застосуйте extractMethod […]


Залишити відповідь

Заповніть поля нижче або авторизуйтесь клікнувши по іконці

Лого WordPress.com

Ви коментуєте, використовуючи свій обліковий запис WordPress.com. Log Out / Змінити )

Twitter picture

Ви коментуєте, використовуючи свій обліковий запис Twitter. Log Out / Змінити )

Facebook photo

Ви коментуєте, використовуючи свій обліковий запис Facebook. Log Out / Змінити )

Google+ photo

Ви коментуєте, використовуючи свій обліковий запис Google+. Log Out / Змінити )

З’єднання з %s

%d блогерам подобається це: