Як ви думаєте, код - це самодокументування? [зачинено]

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

Відповідальний інтерв'ю шукав чорно-білу відповідь, середини не було. Я ніколи не мав можливості запитати про обґрунтування цього питання, але мені цікаво, чому це питання було б поставлено розробнику і про що ви дізнаєтесь з відповіді "так" чи "ні"?

З моєї власної точки зору я можу читати Java, Python, Delphi тощо, але якщо мій менеджер підійде до мене і запитає, як далеко я в проекті, і я кажу "Код на 80% завершений" (і раніше ти починаєш мене знімати, я чув це, як вимовляли розробники в декількох офісах), як саме це самодокументування? Вибачте, якщо це питання здається дивним, але я б краще попросити його і отримати деякі думки з цього приводу, щоб краще зрозуміти, чому воно буде поставлене комусь на інтерв'ю.

Частково.

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

Порівняйте:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

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

Ні. Код сам по собі не є самодокументацією.

Причина полягає в тому, що в коді зазначено ЯК і не піклується про те, ЧОМО це те, що люди повинні знати, щоб підтримувати код.

Отже, вам потрібні додаткові коментарі, що пояснюють усі ЧОМУ . Ви можете обмежити їх, якщо дозволити змінним іменам включити частину рішень, але ви не можете їх уникнути.

Власний код говорить вам " як ". Правильні коментарі говорять вам " чому " .

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

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

Більш повна відповідь полягає в тому, що код повинен бути самодокументованим в максимально можливій мірі, але немає розумного способу включення в код деяких типів документації. Наприклад, код може штрафувати лише за документальне оформлення інформації, яка збирається у формі A, що у формі B, а що на формі C. Як правило, це не може (і, мабуть, не повинно) намагатися документувати тести, що показують, що розділення отримані дані таким чином зменшили помилки x% порівняно з (наприклад), використовуючи лише дві форми замість трьох.

Будь-яке, окрім найтривіальнішого фрагмента коду, може отримати вигоду з принаймні частини зовнішньої документації.

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

Однак, є обмеження щодо того, що можна зробити, зробивши зрозумілим код. У цих випадках потрібно документувати.

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

Про цікаву розмову щодо достоїнств та недоліків коментування дивіться на http://www.perlmonks.org/index.pl?node_id=65153 стару розмову, в якій я був частиною. (Зауважте, в той же час, коли ми мали цю розмову, був приватний набір чатів, які були дружнішими. Я завжди шкодував, що лише більш негативна половина розмови є публічною.) Моя думка вже не точно відповідає тому, що я думав тоді , але я все ще думаю, що розмова вартує їжі для роздумів.

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

В ідеальному світі можна зробити таке твердження:

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

Гаразд, це справедливо, але проблема полягає в тому, що ми не живемо в ідеальному світі. Є певні проблеми з досягненням цього ідеального твердження.

1. Програмісти часто не є експертами в галузі, проти якої програмують. Досить просто зрозуміти таку функцію, як startEngine(Car car)(більшість) кожен може зрозуміти, що тут задають. Але рухайтесь у реальному світі, і справи стають трохи нечіткішими. Наприклад, ця функція getSess(String tid, String aid)була б цілком зрозумілою транспортному інженеру, який розумів системи DWDM, але це може поставити виклик новому програмісту, щойно поставленому на проект. Добре розміщені коментарі можуть допомогти полегшити перехід до розуміння коду вчасно.

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

3. Скільки разів ви писали трохи коду, щоб пізніше постаралися зрозуміти, чому ви це зробили, або навіть те, що ви намагалися досягти? Всі ми робимо це час від часу. Вирішення проблеми та створення легкого для вирішення проблеми часто є двома різними способами мислення. Якщо ви не людина, яка може ідеально писати код поза воротами, ви часто робите багато помилок з кодом, коли йдете разом. Можливо, ви також не зможете ненадовго повернутися до цього коду. Добре розміщені коментарі можуть допомогти полегшити перехід до розуміння коду вчасно.

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

Чудово написаний код "самодокументування" - це радість знайти. Чудово написаний код «самодокументування», з добре розміщеними, інформативними коментарями - це знахідка і дуже рідкісна знахідка.

Просто навести аргументи з кожного боку початкового питання:

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

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

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

Очевидно, він був грамотним програмістом у стилі Кнут. Учневі на LP код повинен бути самодокументованим, щоб бути дійсним. Тож єдина можлива відповідь - «так».

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

Я думаю, що інтерв'юер, можливо, шукав: "Як ви пишете код самодокументування?" з мається на увазі "Яке ваше ставлення до документації?"

Я ходив на справді натхненну лекцію хлопця на ім’я Роберт Мартін одного разу, де він розповідав про розділ «Методи написання» своєї книги «Чистий кодекс».

Він, очевидно, представляв позицію пуриста, але я взяв на борт його поради, коли ви розрізаєте свій код на невеликі методи багаторазового використання та використовуєте прості хитрощі, як-от:

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

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

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

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

Джек Ривз висловив переконливий аргумент, що код - це дизайн . Що стосується багатьох, то фактичний код - це єдиний "документ", який говорить вам, що робить система. Все інше занепадає, оскільки жива система має тенденцію відходити все далі і далі від розробленої системи. Навіть якщо ви створили документ з коду (як це можна зробити в багатьох інструментах UML в даний час), це все одно лише точна документація системи на той момент .

Тож так, код - це самодокументування. Наскільки це добре зафіксовано - це інше питання.

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

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

Я знаю, що відповідь більшості людей на це питання буде "ні", але я збираюся сказати "так". Якби мене в інтерв'ю запитали про роботу, я все одно сказав би так.

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

Для мене код - це кінцева документація. Скільки б ви не написали словами, що програма збирається робити, точна поведінка визначається кодом.

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

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

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

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

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

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

Я навчаюсь багато років, маю ступінь магістра і все ще дію коду, але я не хочу просто писати java і хотів би трохи більше використовувати свій мозок. Погляди UML дають мені те, що мені потрібно для того, щоб подумати про свою архітектуру, спілкуватися з іншими членами команди та створювати кращу архітектуру, не використовуючи розробку Model Driven, а лише дельту між існуючим вручну написаним кодом та графічно створювати діаграми класів. Я створюю свою архітектуру на рівні коду, потім повертаю її назад і дивлюся на модель. Я створюю представлення і намагаюся вдосконалити свою архітектуру безпосередньо в коді, потім знову повернути назад і побачити, що робиться і т.д. ... Це постійна ітерація без генерації коду, що керується моделлю, але жива синхронізація або злиття між кодом і UML. Мені подобається, що код керує UML і, звичайно, не навпаки.