Co powinienem zawrzeć w nagłówku dokumentacji zajęć

Szukam pouczającego formatu dokumentacji klas dla moich klas Entity, Business Logic i Data Access.

Znalazłem następujące dwa formaty stąd

Format 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Format 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Wydaje mi się, że następujące są podstawowe elementy

• Autor
• stworz Date
• Opis
• Historia zmian

tak czy inaczej będzie tam nazwa i nazwa klasy.

Daj mi znać, jaki format jest zalecany i czy istnieje standardowy sposób pisania historii zmian?

Większość informacji, które zasugerowałeś, można znaleźć w repozytorium źródłowym.

Jedyne, czego naprawdę potrzebujesz, to sekcja celu, która mówi, po co jest klasa.

Czy nużące byłoby wyszukiwanie w repozytorium za każdym razem, gdy chcesz poznać inne informacje? Powiedziałbym nie. Jak często zależy Ci na tym, kto był oryginalnym autorem? Lub kiedy plik został utworzony po raz pierwszy? Wtyczki (takie jak Ankh SVN dla Visual Studio) często pozwalają na kliknięcie prawym przyciskiem myszy w bieżącym pliku i wyświetlenie dziennika repoistory dla pliku, więc nie jest to zbyt trudne, aby zobaczyć te informacje.

Dodatkowo, jeśli przechowujesz historię wersji w komentarzu, ten komentarz musi zostać zachowany. Z czasem jest szansa, że ​​może cię okłamać. Repozytorium kodu źródłowego automatycznie przechowuje te dane historyczne, więc nie wymaga konserwacji i będzie dokładne.

Mają opisowe nazwy klas, metod i zmiennych . Wyeliminuje to potrzebę takich komentarzy, jak cel i opis. Czasami myślimy, że im krótsza nazwa metody, tym lepiej. Przeciwnie, stwórz nazwę metody tak długo, jak chcesz, pod warunkiem, że jasno opisuje jej cel. Mają tylko notatki, które są absolutnie niezbędne i pomagają w zrozumieniu kodu w określony sposób. Podczas wprowadzania zmian w kodzie programiści często zapominają o aktualizowaniu komentarzy. Możesz skończyć z zsynchronizowaniem komentarzy i kodu i wyrządzeniem więcej szkody niż pożytku.

Przeczytaj ten artykuł Jeff Atwood - Kodowanie bez komentarzy .

Używam standardowych tagów do generowania dokumentacji. Nic dodać nic ująć. Spójrz tutaj

Nigdy nie umieszczam informacji, które nie należą do klasy. Autor, dane, zmiany to dane do przechowywania w systemie kontroli wersji.

Dwa przedstawione formaty są bezużyteczne do generowania dokumentacji i mają największy błąd w komentarzach, podają historię zmian.

Wiele z tych informacji może być dodanych przez twoje repozytorium kontroli źródła, pozostawiając naprawdę tylko opis, który powinien dokładnie opisać zakres i zachowanie klasy. Jako przykład polecam przyjrzeć się Javadoc dla Java JDK.

Wszystko na tej liście jest niepotrzebne. Kontrola źródła powinna zająć się prawie wszystkim, a tym, czego nie obejmuje, są przestrzegane dobre konwencje nazewnictwa.

Jeśli muszę przeczytać Twój „Opis”, aby dowiedzieć się, co robi twoja klasa, to (a) źle go nazwałeś lub (b) napisałeś złą klasę, która robi zbyt wiele (SRP).

Bawiłem się zmieniając szablony nagłówków, ponieważ, jak zauważają inni, wiele z tych informacji można znaleźć w repozytorium, a do tej pory duże pola, które chciałem zachować, są następujące:

• Opis - co robi kod.
• Uwagi - Wszystko, co należy wiedzieć o kodzie, które nie jest łatwe do uzyskania na podstawie komentarzy w samym kodzie.
• Referencje - Wszelkie referencje, od których zależy kod, nie są wyjaśnione przy użyciu includelub podobnych instrukcji.

Jednym z elementów, który może być przydatny do włączenia, jest sekcja dotycząca słów kluczowych Chociaż możesz być w stanie wyszukać nazwy funkcji, klasy, struktury itp., Mogą istnieć pewne słowa kluczowe, których inne nazwy w pliku nie wyjaśniają. Lub w przypadku starszego, słabo udokumentowanego kodu może to być pierwszy krok do udokumentowania kodu w celu konserwacji.

Większość innych odpowiedzi, które przeczytałem do tej pory, zakładało, że istnieje tylko jedno repozytorium, które jest zawsze dostępne

Ponieważ kod źródłowy może utracić połączenie z repozytorium (tj. Jeśli zostanie skopiowany), moja dokumentacja klasy wygląda następująco:

• class documentation header (= blok komentarza na początku pliku) zawiera tylko wymagane informacje prawne (tj. prawa autorskie xyz na licencji gpl)
• wszystko, co deweloper korzystający z klasy powinien wiedzieć, powinno przejść do komentarza class-java-doc-comments (lub jego odpowiednika .net), aby współczesni ide-s mogli wyświetlać te informacje jako kod podpowiedzi w kodzie źródłowym używającym klasy.

Możesz także dodać numer biletu dla poprawki błędu lub żądania funkcji, abyś mógł dowiedzieć się, gdzie / kiedy / dlaczego klasa została utworzona (jeśli masz szczęście, że nadal możesz uzyskać dostęp do biletów po kilku latach).

Kiedy poproszono mnie o naprawienie problemów w starych, starszych programach zamkniętych, numery biletów były dla mnie bardzo cenne dla zrozumienia oryginalnych wymagań kodu.