Pytania oznaczone «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...

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...

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...

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ść...

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...

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...

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());

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...

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...

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ę...

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ę...

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...

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...

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;...

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ą

Jednym z głównych celów firm zajmujących się tworzeniem oprogramowania jest zwiększenie ich współczynnika autobusu. Jest to również zalecane w rozmowie zorganizowanej przez Google . Oznacza to, że powinieneś zakodować i udokumentować wszystko w taki sposób, że jeśli jutro wpadniesz na autobus,...

Wydaje się, że istnieje awersja do pisania nawet najbardziej podstawowej dokumentacji. Nasze projekty README są stosunkowo puste. Dokumenty nie zawierają nawet zaktualizowanych list zależności. Czy jest coś, czego nie znam w branży, co sprawia, że ​​programiści nie lubią pisać dokumentacji? W...

Pracując nad kodem, mam do czynienia z wieloma takimi samymi wyzwaniami, jakie stawiają moi koledzy z zespołu, i napisałem kilka pomocnych funkcji i klas, a także one. Jeśli jest dobra komunikacja, usłyszę o czymś wspaniałym, co ktoś złożył, a sześć miesięcy później, gdy będę jej potrzebować, mogę...

Uważam, że piszę (mam nadzieję) pomocne komentarze w dokumentacji typu C ++: The reason we are doing this is... Powodem, dla którego używam słowa „my” zamiast „ja” jest to, że dużo piszę w środowisku akademickim, gdzie „my” jest często preferowane. Oto pytanie. Czy istnieje dobry powód, aby...

Program CS mojej szkoły unika jakiejkolwiek wzmianki o programowaniu obiektowym, więc czytam sam, aby go uzupełnić - w szczególności Object Oriented Software Construction autorstwa Bertrand Meyer. Meyer wielokrotnie podkreśla, że ​​klasy powinny ukrywać jak najwięcej informacji o ich...