Як посилатися на конкретні області коду в документації?

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

У цьому випадку не має сенсу посилатися на конкретний номер рядка, оскільки додавання або видалення одного рядка коду негайно застаріло б у документації. Чи існує якась найкраща практика для посилання на певний рядок коду без посилання на нього за номером рядка?

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

/* linetag 38FECD4F */

Де "38FECD4F" - це унікальний тег для цього конкретного рядка. Тоді я можу помістити в документацію "На рядку з тегом" 38FECD4F ", помітити, що таке і таке трапляється".

Будь-які інші ідеї? Я відчуваю, що як правило, краще документувати кодові одиниці в цілому, а не окремі їх частини, але у випадку з цим конкретним проектом існують ДЛІВНІ коси процесуального кодексу, які ніколи не були перероблені на менші одиниці.

documentation comments

— самотній човен
джерело

Ви посилаєтесь на конкретні місця з методів вкладення або з коментарів, що резюмують верхній частині файлу? В останньому випадку ви можете використовувати стиль "#" JavaDoc.

— арін

Я зазвичай посилався на файл і метод ("Повідомлення у файлі ABC у методі XYZ таке-і-таке буває"), але мені цікаво дізнатися, які відповіді надходять.

— Майкл Іцо

Чи не було б доцільніше в цих випадках просто помістити коментарі до фактичного коду?

— Роберт Харві

чи є в команді хтось, хто міг би переглянути вашу документацію та надати відгук?

— гнат

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

— Майкл Шоу

Відповіді:

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

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

Я не знаю жодного стандартного способу зробити це - але вгорі голови ...

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

Зауважте вище визначення func1 (), що таке і таке трапляється

Зауважте, що відразу після циклу for, який повторюється над recordXYZItr, ми також викликаємо метод gc ()

Обережно: у методі yahoo (), одразу після оголошення змінної PQ, ми також підміняємо значення A і B, тому об'єкт mapABC також потрібно скопіювати

Інший спосіб - додавання описових тегів. Замість того , щоб що - щось на зразок 38FECD4F, ви можете сказати , Some XYZ implementationчи BUGFIX 1474, а потім звернутися до цього де - то ще.

— деревокодер
джерело

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

— самотній човен

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

— Thijs van Dien

@ThijsvanDien: Повірте, ми багато чого робимо не так, як тут! ;-)

— самотній човен

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

Але ... якщо вам потрібно посилатися на певний рядок коду як цілу одиницю, чи не означає це, що його деякий код, який представляє абстрактну операцію, і, таким чином, може бути відновлений у своєму власному методі / функції? Після використання методу його досить легко, просто зверніться до namespace.class.methodЗвичайно, це означає, що існують дуже маленькі методи, довжиною близько 5-10 рядків або навіть менше. За допомогою Doxygen ви можете розмістити документацію поверх методу, і він завжди буде синхронізуватися з назвою методу / класу / простору імен.

— Лоран Буро-Рой
джерело

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

— Росс Паттерсон

Я пропоную вам скористатися іншим підходом, окрім посилання з деякої кодової зовнішньої документації на код:

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

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

— miraculixx
джерело