Co należy umieścić w komentarzach nagłówka u góry plików źródłowych?

Question

Mam wiele plików kodu źródłowego napisanych w różnych językach, ale żaden z nich nie ma standardowego komentarza na górze (czasami nawet w ramach tego samego projektu). Niektóre z nich nie mają żadnego komentarza nagłówkowego :-)

Zastanawiam się nad stworzeniem standardowego szablonu, którego mogę użyć u góry moich plików źródłowych i zastanawiałem się, które pola powinienem uwzględnić.

Wiem, że chcę dołączyć moje imię i krótki opis tego, co plik zawiera/robi. Czy powinienem również podać datę utworzenia? Data ostatniej modyfikacji? Programista, który ostatnio zmodyfikował plik? Jakie inne dziedziny okazały się przydatne?

Wszelkie wskazówki i komentarze mile widziane.

Dzięki,
Cameron

Answer 1

Data utworzenia, data modyfikacji i autor, który ostatnio zmieniony plik powinien być przechowywany w oprogramowaniu sterującym źródła.

I zazwyczaj umieścić:

• Głównym celem pliku i rzeczy w pliku.
• Projekt/moduł, do którego należy plik.
• Licencja powiązana z plikiem (i plikiem LICENCJA w katalogu głównym projektu).
• Kto jest odpowiedzialny za akt (albo zespół, osoba, lub obu)

Answer 2

użyteczne pola, które wymienione są dobre. Kto zmodyfikował plik i kiedy.

Oprogramowanie do kontroli wersji powinno umożliwiać osadzanie słów kluczowych w komentarzach. Na przykład w CVS, $ Id $ rozwiąże plik, datę/czas zmodyfikowany i użytkownik, który zmodyfikował plik. Będzie automatycznie aktualizowany przy każdym zameldowaniu.

Answer 3

To wydaje się być umierającą praktyką.

Niektóre osoby na StackOverflow są całkowicie przeciwne komentarzom do kodu (rozumowanie, że kod powinien być napisany jako zrozumiały) Chociaż nie posunąłbym się tak daleko, niektóre z punktów tłumu anty-komentującego mają sens, takie jak fakt, że komentarze wydają się być nieaktualne.

Bloki nagłówków komentarzy jeszcze bardziej cierpią z powodu tych symptomów. Każda organizacja, w której byłem, miała te bloki nagłówków, są one nieaktualne. Mają autorską nazwę jakiegoś faceta, który nawet tam nie pracuje, opis, który w ogóle nie pasuje do kodu (zakładając, że tak się stało) i data ostatniej modyfikacji, która kiedyś była porównywana z historią kontroli wersji, wydawała się nie mieć znaczenia jego ostatnie kilkanaście aktualizacji.

W mojej osobistej opinii, zachowaj komentarze blisko kodu. Jeśli chcesz poznać przeznaczenie i/lub historię pliku kodu, użyj swojego systemu kontroli wersji.

Answer 4

Jakie pola są potrzebne? Jeśli musisz zapytać, czy umieścić tam jakieś informacje, naprawdę nie potrzebujesz tych informacji. Jeśli nie jesteś zmuszany, przez jakąś biurokratyczną niekompetencję twojego pracodawcy, nie rozumiem, dlaczego powinieneś szukać więcej informacji, niż ci się wydaje, że powinno tam być.\

Answer 5

Nie wspomniałeś, że używasz systemu kontroli wersji, a twój komentarz w odpowiedzi Neila N potwierdza to dla twojego starszego kodu. Podczas korzystania z kontroli wersji jest to najlepszy sposób na to, że doświadczyłem wielu sytuacji, w których koszt zrobienia tego dla starszego kodu nie byłby pokryty przez sponsora projektu. Jeśli nie masz scentralizowanej historii zmian dla projektu, historię zmian można umieścić w modułach. Dobrze, że używasz systemu kontroli wersji dla nowego kodu.

Your company name 
All rights reserved (c) year - or reference to appropriate license 

Project or library this file is for 

Module it belongs to 

Description of what it contains 

History 
------- 
01/08/2010 - Programmer - version 
    Initial creation. 
01/09/2010 - Programmer - version 
    Change description. 
01/10/2010 - Programmer - version 
    Change description. 

Answer 6

W większości organizacji, wszystkie pliki źródłowe muszą zaczynać się od notki prawnej. Jeśli naprawdę masz szczęście, to jest to jeden liniowiec, ale w większości przypadków jest to naprawdę długi blok prawniczy. W rezultacie niewiele osób kiedykolwiek je czyta. Nasze oko po prostu podróżuje do pierwszego elementu programu, a następnie przechodzi do jego dokumentacji.

Jeśli więc chcesz napisać cokolwiek, zapisz go w powiązaniu z najwyższym elementem programu, a nie z plikiem.

Wszelkie inne informacje dotyczące księgowania powinny być na ogół częścią kontroli wersji, a nie utrzymywane (słabo) w samym pliku.

Answer 7

Oprócz powyższego komentarza podającego licencję, projekt, do którego należy, itp., Staram się również umieszczać "dziwne" wymagania na górze (takie jak "zbudowany z wersją X biblioteki Y"), tak aby ty, lub osoba, która je podnosi po tym, jak nie zmienisz czegoś, na czym program polega, nie zdając sobie z tego sprawy (lub, jeśli tak, to przynajmniej wiedzą, co zmienić)

Answer 8

Powrót w 2002 roku, kiedy Po ukończeniu college'u i pracy nie było mi wiele, połączyłem się z firmą usługową, która tworzyła oprogramowanie dostosowane do swoich klientów w Javie. Musiałem usiąść w biurze klienta (który był zepsutym pokojem w elektrycznym podstacji uzbrojonym w prąd zmienny, aby utrzymywały serwery), dzieląc krzesła/komputery z innymi facetami w zespole. Pozostali inżynierowie (jeśli mogę nazwać ich inżynierami;) w grupie używanej do wprowadzania zmian ad-hoc do kodu źródłowego, kompilują pliki i wprowadzają je do produkcji.

• Nie ma sposobu, aby dowiedzieć się, kto dokonał jakiej zmiany.
• Nie ma sposobu, aby dowiedzieć się, dlaczego wprowadzono jakąkolwiek zmianę.
• Nie można przejść do poprzedniej wersji kodu, chyba że inżynier "zapamiętał" to, co zmodyfikował.
• Kopia zapasowa: Skopiuj pliki z serwera produkcyjnego, które zostały zastąpione nowymi plikami.
• Lokalizacja kopii zapasowej: Katalog domowy inżyniera, który kopiuje pliki na serwer produkcyjny.

Raporty o serwerach produkcyjnych, które uległy awarii w związku z nieudanymi próbami kopiowania plików na serwer (pominięcie kopiowanego pliku, zgubienie kopii zapasowych lub skopiowanie niepoprawnych plików lub skopiowanie wszystkich plików) spotkałem się z wzruszeniem ramion (o nie, czy to w dół? zobaczmy, co się stało, hej, który zmienił to, co ostatnio ...? ummm ...).

Podczas tych dni, po spędzeniu kilku frustrujących dni próbuje dowiedzieć się whos i whys tył kodu, ja wymyślił system komentarzy na liście w nagłówku pliku źródłowego, który szczegółowo następujące:

1. Data zmiany dokonane
2. kto dokonał zmiany
3. Dlaczego dokonano zmiany

Dwa miesiące później, gdy lista zagrożonych zakwestionować chowania rozmiaru e kodu źródłowego w pliku menedżer miał świetny pomysł na uzyskanie systemu kontroli wersji źródłowej.

Nigdy nie musiałem umieszczać żadnych komentarzy w nagłówkach plików źródłowych (z wyjątkiem informacji o prawach autorskich) w żadnej firmie, w której pracowałem od tego czasu. W mojej obecnej firmie wszystko inne jest w większości oczywiste, patrząc na kod lub przechodząc do systemu zgłaszania błędów, który jest zintegrowany z systemem kontroli wersji źródłowej.

Answer 9

Wiele zależy od tego, czy używasz narzędzia do generowania dokumentacji automatycznej, czy nie.

Chociaż zgadzam się z wieloma komentarzami, jeśli używasz JavaDoc lub innego narzędzia do generowania dokumentacji, które zależy od komentarzy, oczywiście musisz dołączyć to, co chce zobaczyć.

Answer 10

Zawiera następujące informacje:

• Co plik ten jest dla. To bardzo przydatna wiedza i jest ważniejsza niż cokolwiek innego. Powinieneś powiedzieć czytelnikowi, dlaczego istnieje taki plik, dlaczego zgrupowałeś funkcje w oddzielnym pliku/pakiecie/module i dlaczego są one używane. Może krótko, jeden lub dwa wiersze, ale powinno tam być.
• Legalne rzeczy, jeśli aplikantem.
• Zostaw miejsce dla specjalnych poleceń edytorów konsoli, takich jak Emacs.
• Dodaj specjalne polecenia wymagane przez system automatycznego dokumentowania.

Things rzeczy, które powinnaś nie obejmują są

• Kto stworzył plik
• kiedy został utworzony
• kto to zmodyfikowany po raz ostatni
• kiedy był ostatnio modyfikowany
• Co zostało dodane najnowszą modyfikacją

Możesz - i powinieneś - pobrać go przez system kontroli wersji, gdzie jest stale i automatycznie aktualizowany. Nie mówiąc już o tym, że większość z tych punktów jest po prostu bezużyteczna.