Tego nigdy mnie nie nauczono. Widziałem wiele różnych stylów tworzenia. Piszę głównie w Javie i Pythonie. Zastanawiałem się, czy istnieje standardowy styl autorskie, czy wszystko jest w stylu dowolnym. Również jeśli odpowiesz, czy nie masz nic przeciwko dołączeniu stylu, którego używasz do tworzenia plików, które tworzysz w domu lub w pracy.
Zwykle po prostu idę
@author garbagecollector
@company garbage inc.
programming-practices
zakurzony programista
źródło
źródło
Odpowiedzi:
Nie jestem do końca pewien, o co pytasz, ale używam bardzo surowego stylu:
Styl inspirowany jest programistami montażu.
Umieszczam to na górze stron, które muszę „Autor”, niezależnie od tego, czy jest to klasa, plik tekstowy, procedura przechowywana SQL itp.
źródło
Dlaczego miałbyś? to jest zadanie systemu kontroli wersji i „Winy” :)
źródło
W mojej firmie nie zajmujemy się pisaniem. Zamiast tego pozwalamy naszej kontroli wersji sobie z tym poradzić.
Przy każdym zameldowaniu dołącza nazwę użytkownika do listy zmian. Jeśli coś jest zepsute, ktoś może cofnąć się i spojrzeć na historię zmian, aby zobaczyć, co się zmieniło, kiedy i kto to zrobił. Dobrze jest również spojrzeć na wykres wersji, aby zobaczyć, jak plik ewoluował w czasie, kto go dotknął, jakie projekty się z niego rozgałęziły.
Problem, jaki widzę przy umieszczaniu znacznika autora w klasie, polega na tym, że z czasem jest prawdopodobne, że więcej niż jeden programista będzie pracował nad tą klasą. Aktualizacje i tym podobne. To dodatkowy krok, aby zaktualizować ten komentarz autora, a dodatkowe małe kroki są często zapominane. W ten sposób szybko staje się nieaktualny.
źródło
W ogóle tego nie robię. Myślę, że w pracy mamy szablon, który jest wstawiany do plików z nazwą firmy i identyfikatorem użytkownika osoby, która jako ostatnia zmodyfikowała plik, ale nigdy nie zwracam na to uwagi.
Ogólnie rzecz biorąc, nie sądzę, że to naprawdę ma znaczenie, jak to robisz. Jeśli chcesz automatycznie stemplować pliki, wybierz spójny styl i idź z nim.
źródło
JavaDoc jest bardzo standardem w społeczności Java:
http://download.oracle.com/javase/1.3/docs/tooldocs/win32/javadoc.html#@author
źródło
Myślę, że najlepiej pozostawić to systemowi kontroli wersji.
źródło
Podoba mi się funkcja obwiniania w GIT. Możesz zobaczyć, kto jest autorem każdej części / linii kodu. Nie tylko plik.
źródło
Jeśli pracujesz nad dużym projektem z wieloma współautorami, adnotacje dla każdego pliku z listą autorów po prostu nie działają. Co robisz z listą autorów, dzieląc plik na kilka mniejszych plików? Czy zachowałeś oryginalną nazwę autora, jeśli całkowicie przepisałeś kod? Czy dodajesz swoje nazwisko do listy autorów, gdy naprawiasz literówkę w komentarzu?
Te pytania lepiej pozostawić systemowi kontroli wersji.
Ale nie jestem całkowicie przeciwny liście autorów. Prowadzenie listy autorów całego projektu ma sens. Jeśli jest to projekt z jednym plikiem, na pewno trzymaj go w tym samym pliku. Jeśli jest to większy projekt, przechowuj go w README lub pliku źródłowym najwyższego poziomu (aka main.c). Ale nie powtarzaj się, wymieniając autorów w każdym pliku.
źródło
Śledzimy za pomocą systemu kontroli wersji lub poprzez umieszczenie
@author
w kodzie. Innym sposobem jest powiedzenie bardziej ogólnie, że niektóre osoby były autorami całych modułów lub całego programu. To zachęca ludzi do myślenia o sobie jako o członku zespołu, a nie o zębatce w maszynie, która odpowiada za dokładnie X funkcji lub linii kodu.źródło
Używam komentarzy w stylu Doxygen (lub czasami KernelDoc) do prawie wszystkiego. Pracuję głównie w C i PHP, gdzie Doxygen jest dość popularny.
W większości przypadków pomocne jest co najmniej następujące informacje:
Powinno to pomóc każdemu, kto akurat pracuje nad plikiem, wiedzieć, co ma, co może z nim zrobić i kogo może poprosić o pomoc, jeśli tego potrzebuje. Mówi im także, czy patrzą na coś 10 lat.
źródło
Nie robię tego osobiście, ponieważ jest to dodatkowa dokumentacja, która, jak powiedzieli inni, znajduje się w kontroli wersji. Ale gdybym miał zamiar zrobić snippit z kodu kung-fu, prawdopodobnie byłbym skłonny zastosować wszystko, co moje IDE było w stanie wygenerować automatycznie.
Na przykład, używanie w Delphi 7 z tymi pomocnymi zainstalowanymi CNTools piszę
i wychodzi
potem piszę
i wychodzi
Wyobrażam sobie, że odpowiada to temu, co może pochwycić jakieś narzędzie innej firmy, ale jeśli chodzi o mnie - mam standard, którego nawet nie musiałem wymyślić i zepsuć.
źródło