Як документувати обов'язково складні структури коду?

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

Це дійсно залежить від того, наскільки складний код і математика. Сам код повинен - ​​як завжди - бути максимально самодокументованим. Назвіть змінні правильно, реалізуйте логічні та стислі методи (а не мега-функції), додавайте вбудовану документацію, де це доречно (тобто, коли не очевидно, що саме робить код).

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

Хороший приклад - деяка робота, яку я зробив над нечітким узгодженням тексту. Я провів значні дослідження алгоритмів і реалізував те, що відомо як "алгоритм Сміта-Уотермана" (який насправді використовується для послідовностей ДНК, але загалом стосується "узгодження"). Тож замість простої реалізації алгоритму я знайшов посилання в Інтернеті і включив посилання-два. Як було сказано вище, це демонструє, що (а) мій алгоритм відповідає опублікованому алгоритму, і (б) алгоритм був переглянутий і показано, що він працює.

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

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

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

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

Ви не повинні робити пошук в Інтернеті.