Jak odwoływać się do określonych obszarów kodu w dokumentacji?

Mam zamiar opuścić projekt i zanim odejdę, mój szef poprosił mnie o udokumentowanie kodu (nie udokumentowałem zbyt dobrze). To nie jest wielka sprawa, projekt nie jest strasznie skomplikowany. Ale w mojej dokumentacji znajduję miejsca, w których chciałbym powiedzieć: „Zawiadomienie w linii XYZ, że takie i takie się zdarzają”.

W takim przypadku odwołanie do określonego numeru wiersza nie ma sensu, ponieważ dodanie lub usunięcie pojedynczej linii kodu spowodowałoby natychmiastowe przedawnienie dokumentacji. Czy istnieje jakaś najlepsza praktyka odnosząca się do określonego wiersza kodu bez odwoływania się do niego po numerze wiersza?

Rozważyłem zaśmiecanie kodu komentarzami takimi jak:

/* linetag 38FECD4F */

Gdzie „38FECD4F” jest unikalnym znacznikiem dla tej konkretnej linii. Następnie mogę umieścić w dokumentacji: „W wierszu oznaczonym„ 38FECD4F ”zauważ, że coś takiego i takiego się dzieje”.

Jakieś inne pomysły? Wydaje mi się, że ogólnie lepiej jest dokumentować jednostki kodu jako całość, niż konkretne części, ale w przypadku tego konkretnego projektu istnieją DŁUGIE pokosy kodu proceduralnego, które nigdy nie zostały przekształcone w mniejsze jednostki.

Jeśli dobrze to rozumiem, masz wyjątkowy problem. To, co chcesz to zrobić, odnosi się do określonego wiersza kodu w komentarzach zapisanych w innej części tego samego kodu.

Zwykle nie spotykam się z takimi scenariuszami, w których muszę odwoływać się do wiersza szczegółowego # w komentarzu napisanym gdzie indziej - ogólnie kod jest udokumentowany tam, gdzie jest napisany.

Nie znam żadnego standardowego sposobu na zrobienie tego - ale z góry mojej głowy ...

Możesz odwoływać się do części kodu poprzez jego kontekst - tj. Otaczające je rzeczy.

Zauważ powyżej definicji func1 (), że takie a takie zdarzają się

Zauważ, że zaraz po pętli for, która iteruje przez recordXYZItr, również wywołujemy metodę gc ()

Uwaga: W metodzie yahoo (), zaraz po deklaracji zmiennej PQ, zamieniamy również wartości w A i B, więc tam należy również skopiować obiekt mapABC

Innym sposobem jest dodanie znaczników opisowych. Zamiast czegoś takiego 38FECD4Fmożesz powiedzieć Some XYZ implementationlub BUGFIX 1474, a następnie odnieść się do tego gdzie indziej.

Wiele zależy od tego, w jaki sposób napisano kod, i rozumiem, że może to spowodować szereg refaktoryzacji, których nie jesteś tutaj do zrobienia.

Ale ... jeśli chcesz odwoływać się do określonego wiersza kodu jako całości, czy nie oznacza to, że jest to jakiś kod reprezentujący abstrakcyjną operację, a zatem można go refaktoryzować we własnej metodzie / funkcji? Kiedy jest już w metodzie, jest dość łatwa, po prostu odwołaj się do namespace.class.methodOczywiście oznacza to, że masz metody, które są bardzo małe, około 5-10 linii długości lub nawet mniej. Dzięki Doxygen możesz umieścić dokumentację na górze metody i zawsze będzie ona zsynchronizowana z nazwą metody / klasy / przestrzeni nazw.

Sugeruję inne podejście, niż łączenie dokumentacji zewnętrznej do kodu:

1. dodaj komentarze do swojego kodu, używając narzędzia takiego jak doxygen .

2. jeśli zajdzie potrzeba wyjaśnienia niektórych koncepcji bardziej szczegółowo niż jest to odpowiednie w (nowo utworzonej) dokumentacji kodu, zawsze możesz utworzyć osobny dokument i link do niego.

W ten sposób możesz łatwo wygenerować dokumentację jako stronę internetową lub plik PDF i pozostaje ona zgodna z kodem. Używanie niektórych sztucznych znaczników stanie się bardzo trudne do utrzymania, a jeszcze trudniejsze do zrozumienia dla niewtajemniczonych.