Pytania otagowane jako comments

Pytania dotyczące pisania komentarzy w kodzie.

3
Czy podpowiedzi typu docblock są zbędne podczas używania ścisłego pisania
Mam dość dużą prywatną bazę kodów, która ewoluowała od około dziesięciu lat. Nie używam phpDocumentor, ale odkąd używanie sekcji docblock stało się całkiem standardem w projektach open source, zaadaptowałem pisanie docblocków dla wszystkich metod publicznych w moim repozytorium. Większość bloków zawiera tylko krótki opis i wskazówki dotyczące wszystkich parametrów i …
12 php  comments 
2
Czy rozpowszechnianie kodu z refaktoryzacją komentarzy to dobry pomysł?
Pracuję nad projektem „kodu spaghetti” i podczas gdy naprawiam błędy i wdrażam nowe funkcje, robię też pewne refaktoryzacje, aby kod mógł być testowany jednostkowo. Kod jest często tak ściśle powiązany lub skomplikowany, że naprawienie małego błędu spowodowałoby przepisanie wielu klas. Postanowiłem więc narysować linię w kodzie, w której przestaję refaktoryzować. …
6
Czy komentarze są uważane za formę dokumentacji?
Kiedy piszę dla siebie małe skrypty, układam swój kod wysoko w stos z komentarzami (czasami komentuję więcej niż koduję). Wiele osób, z którymi rozmawiam, mówi, że powinienem dokumentować te skrypty, nawet jeśli są one osobiste, więc jeśli kiedykolwiek je sprzedam, będę gotowy. Ale czy komentarze nie są formą dokumentacji? Czy …
3
Czy komentarze XML są niezbędną dokumentacją?
Kiedyś byłem fanem wymagania komentarzy XML do dokumentacji. Od tego czasu zmieniłem zdanie z dwóch głównych powodów: Podobnie jak dobry kod, metody powinny być zrozumiałe. W praktyce większość komentarzy XML to bezużyteczny szum, który nie zapewnia żadnej dodatkowej wartości. Wiele razy po prostu używamy GhostDoc do generowania ogólnych komentarzy, a …
5
Czy komentarz do metody powinien zawierać zarówno podsumowanie, jak i zwrócony opis, gdy często są tak podobne?
Jestem zwolenniczką odpowiednio udokumentowanego kodu i doskonale zdaję sobie sprawę z jego wad . To nie wchodzi w zakres tego pytania. Lubię przestrzegać zasady dodawania komentarzy XML dla każdego członka publicznego, biorąc pod uwagę, jak bardzo lubię IntelliSense w Visual Studio. Jest jednak jedna forma redundancji, która przeszkadza nawet tak …
1
Co oznacza „TILT” w komentarzu?
Czytam Clean Code autorstwa Roberta C. Martina, a wyrażenie w TILTniewytłumaczalny sposób pojawia się w niektórych przykładach kodu. Przykład (nawiasem mówiąc, jest w Javie): ... public String errorMessage() { switch (status) { case ErrorCode.OK: // TILT - Should not get here. return ""; case ErrorCode.UNEXPECTED_ARGUMENT: return "Unexpected argument"; case ErrorCode.MISSING_ARGUMENT: …
3
Jak odwoływać się do określonych obszarów kodu w dokumentacji?
Mam zamiar opuścić projekt i zanim odejdę, mój szef poprosił mnie o udokumentowanie kodu (nie udokumentowałem zbyt dobrze). To nie jest wielka sprawa, projekt nie jest strasznie skomplikowany. Ale w mojej dokumentacji znajduję miejsca, w których chciałbym powiedzieć: „Zawiadomienie w linii XYZ, że takie i takie się zdarzają”. W takim …
8
Dlaczego wszyscy piszą komentarze do zrobienia dużymi literami? [Zamknięte]
W obecnej formie to pytanie nie pasuje do naszego formatu pytań i odpowiedzi. Oczekujemy, że odpowiedzi poparte będą faktami, referencjami lub wiedzą fachową, ale to pytanie prawdopodobnie będzie wymagało debaty, argumentów, ankiet lub rozszerzonej dyskusji. Jeśli uważasz, że to pytanie można poprawić i ewentualnie ponownie otworzyć, odwiedź centrum pomocy w …
9 comments 
7
Style komentowania / dokumentacji w kodzie
To może być głupie pytanie, ale przez jakiś czas było w mojej głowie i nigdzie indziej nie mogę znaleźć porządnej odpowiedzi. Mam nauczyciela, który mówi, że powinniśmy wyraźnie wymienić każdy parametr z opisem, nawet jeśli jest tylko jeden. Prowadzi to do wielu powtórzeń: double MyFunction(const int MyParam); // Function: MyFunction …
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.