Pytania otagowane jako documentation

Wiele osób twierdzi, że „komentarze powinny wyjaśniać„ dlaczego ”, ale nie„ jak ””. Inni twierdzą, że „kod powinien być samodokumentujący”, a komentarze powinny być rzadkie. Robert C. Martin twierdzi, że (przeformułowany na moje własne słowa) często „komentarze są przeprosinami za źle napisany kod”. Moje pytanie jest następujące: Co jest złego …

236 programming-practices  documentation  comments 

Zostałem specjalnie poproszony o udzielenie wyjaśnienia lub komentarza wiersz po wierszu (lub odpowiednio - na przykład obraz po obrazie itp.), Który mój szef chce móc przeczytać i śledzić. Ponieważ nie jest programistą, nie może postępować zgodnie z kodem, dlatego chce, aby wszystko zostało przetłumaczone na angielski. Czy ktoś wcześniej został …

155 documentation 

Standard RFC 2606 zastrzega nazwy domen example.org , example.net i example.com w celu wykorzystania jako przykłady w dokumentacji. Jaki jest odpowiednik numeru telefonu (w tym kodu kraju), który może być użyty jako przykład, np. W celu podania użytkownikom przykładu, w jakim formacie należy wprowadzić numery telefonów? W najlepszym przypadku byłby …

112 documentation  standards  help-documentation 

Załóżmy, że rozwijam stosunkowo duży projekt. Udokumentowałem już wszystkie moje klasy i funkcje w Doxygen, jednak wpadłem na pomysł, aby umieścić „uwagi programisty” na każdym pliku kodu źródłowego. Ideą tego jest wyjaśnienie laikom, jak działa określona klasa (i nie tylko dlaczego, jak większość komentarzy). Innymi słowy, aby dać innym programistom …

104 documentation  large-scale-project 

Podczas spotkania dotyczącego wycofania SDK innej firmy z najnowszej wersji zauważono, że nasi programiści już zaznaczyli w historii zatwierdzeń, że najnowszej wersji nie należy używać. Niektórzy programiści twierdzili, że była to zła praktyka i powinna była zostać odnotowana w pliku źródłowym (tj. // Don't upgrade SDK Version x.y.z, see ticket …

94 version-control  documentation 

Pracuję nad dość dużym projektem i dostałem zadanie wykonania kilku tłumaczeń. Było mnóstwo etykiet, które nie zostały przetłumaczone i podczas gdy przeglądałem kod, znalazłem ten mały fragment kodu //TODO translations To sprawiło, że pomyślałem o znaczeniu tych komentarzy dla siebie (i innych?), Ponieważ miałem wrażenie, że większość programistów po tym, …

86 documentation  comments 

Napisałem następujący kod: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Jest tutaj komentarz z komentarzem. Ale myślę, że dzięki temu kod staje się bardziej przejrzysty, ponieważ …

83 documentation  comments 

Po pierwsze, w tym pytaniu chciałbym trzymać się z dala od polemiki dotyczącej tego, czy komentowanie kodu źródłowego jest dobre czy złe. Po prostu staram się lepiej zrozumieć, co ludzie mają na myśli, gdy mówią o komentarzach, które mówią DLACZEGO, CO I JAK. Często widzimy wytyczne takie jak „Komentarze powinny …

78 documentation  comments 

Pracowałem nad projektem trzy miesiące temu, a potem nagle pojawił się kolejny pilny projekt i zostałem poproszony o zwrócenie mojej uwagi. Od jutra wracam do starego projektu. Zdaję sobie sprawę, że nie pamiętam, co dokładnie robiłem. Nie wiem od czego zacząć. Jak mogę udokumentować projekt, aby za każdym razem, gdy …

72 project-management  documentation 

Planuję zrezygnować z mojej obecnej pracy, ponieważ jesteśmy zablokowani w korzystaniu z Blub , z korporacyjnym środowiskiem Blub i serwerem WWW na poziomie Blub, na przeciętnym hostingu współdzielonym. Moi współpracownicy są przyjaźni, a mój szef jest przeciętnym właścicielem małej firmy - chcę całkowicie odejść z przyczyn technicznych. Mam wrażenie, że …

66 career-development  documentation 

Rozumiem znaczenie dobrze udokumentowanego kodu. Ale rozumiem również znaczenie samodokumentowania kodu. Im łatwiej jest wizualnie odczytać określoną funkcję, tym szybciej możemy przejść podczas konserwacji oprogramowania. Powiedziawszy to, lubię rozdzielać duże funkcje na inne mniejsze. Ale robię to do tego stopnia, że ​​klasa może mieć w górę pięć z nich tylko …

63 programming-practices  code-quality  documentation 

Automatyczne generowanie dokumentacji można wykonać za pomocą różnych narzędzi, a GhostDoc jest jednym z bardziej znanych. Jednak z definicji wszystko, co generuje, jest zbędne. Przegląda nazwy metod, klas itp. I wyświetla angielski, który mógłby wyjaśnić je bardziej dosłownie. W najlepszym przypadku robi to, co czytelnik mógłby zrobić w swojej głowie …

60 documentation  automation  automatic-programming 

Piszę dokumentację użytkownika (SOP), która obejmuje programy innych firm, które staram się dobrze opisać. Jednym z takich programów jest serwer, który oferuje niewiele informacji na temat uruchamiania, poza grafiką pokazującą się podczas procedury uruchamiania / uruchamiania. Jako programista użyłem tego okna jako szybkiego wskaźnika statusu i chciałbym przekazać to mojej …

59 documentation  component  jargon 

Czasami znajduję się w sytuacjach, gdy część kodu, który piszę, jest (lub wydaje się być ) tak oczywista, że ​​jej nazwa byłaby w zasadzie powtarzana jako komentarz: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } (Przykład w …

54 programming-practices  documentation  language-agnostic 

Kiedy używasz narzędzi takich jak jsdocs , generuje on statyczne pliki HTML i ich style w bazie kodu na podstawie komentarzy w kodzie. Czy te pliki powinny być rejestrowane w repozytorium Git, czy powinny być ignorowane za pomocą .gitignore?

49 git  documentation