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

9

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.

samotna łódź
źródło
Czy odwołujesz się do konkretnych lokalizacji z metod obejmujących lub z komentarzy podsumowujących na początku pliku? W tym drugim przypadku możesz użyć stylu JavaDoc „#”.
arin 28.12.12
Zwykle odnosiłem się do pliku i metody („Zawiadomienie w pliku ABC w metodzie XYZ takie-i-takie się zdarza”), ale jestem ciekawy, jakie odpowiedzi się pojawią.
Michael Itzoe
7
Czy nie byłoby bardziej celowe w tych przypadkach, aby po prostu wstawić komentarze do rzeczywistego kodu?
Robert Harvey
czy jest ktoś w zespole, kto mógłby przejrzeć twoją dokumentację i przekazać opinie?
komar
Potrzeba tego wydaje się bardzo podobna do efektów ubocznych innych metod, z których wyraźnie korzystasz.
Michael Shaw

Odpowiedzi:

1

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.

treecoder
źródło
Dzięki za opinie! Myślę, że „opisz to kontekst” wygląda dla mnie jak najlepsza opcja. Dzięki jeszcze raz.
loneboat
2
Unikalny problem dość często oznacza, że ​​robisz coś w niewłaściwy sposób.
Thijs van Dien
2
@ThijsvanDien: Zaufaj mi, robimy DUŻO rzeczy w niewłaściwy sposób! ;-)
loneboat
3

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.

Laurent Bourgault-Roy
źródło
1
Ta odpowiedź powinna być zwycięzcą, z wyjątkiem oryginalnego punktu widzenia OP, że odchodzi z projektu i przypuszczalnie ma ograniczony czas, a także prawdopodobnie nie powinien wprowadzać zmian w drodze do wyjścia. Ale absolutnie poprawne - jeśli coś jest na tyle skomplikowane, że można się do niego odwoływać zewnętrznie, umieść je we własnej nazwanej jednostce kodu.
Ross Patterson
2

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.

miraculixx
źródło