W trakcie programowania pojawi się kilka komentarzy wyjaśniających kod i kilka komentarzy usuwających kod:
// A concise description
const a = Boolean(obj);
//b = false;
Czy istnieje dobra metoda szybkiego parsowania, która jest która?
Bawiłem się przy użyciu 3 /
i /** */
do opisowych komentarzy.
Użyłem również wtyczki VSCode do wyróżnienia //TODO:
i//FIXME:
///
a/** ... */
komentarze są także wykorzystywane przez niektórych wytwórców dokumentacji, takich jak Doxygen lub JSDoc. Jeśli użyjesz ich lub podobnych narzędzi, możesz nie być w stanie użyć tego rodzaju komentarza do opisowych komentarzy, które nie są przeznaczone do dokumentacji.Odpowiedzi:
Jest na to bardzo proste rozwiązanie: usuń skomentowany kod.
Naprawdę istnieją tylko dwa dobre powody, aby skomentować kod: przetestować coś / naprawić lub zapisać kod, którego możesz użyć później. Jeśli testujesz lub naprawiasz coś, usuń skomentowany kod, jak tylko skończysz test lub poprawkę. Jeśli zapisujesz kod, którego możesz użyć później, uczyń go kodem pierwszej klasy i umieść go gdzieś, na przykład w bibliotece, w której można go dobrze wykorzystać.
źródło
Dodając do doskonałej odpowiedzi @ RobertHarvey, uważam, że istnieje tylko jeden uzasadniony powód, dla którego kiedykolwiek spotkałem się z zapisaniem skomentowanego kodu w kontroli źródła, nawet tymczasowo: w przypadku nieoczywistego kodu zastępczego, który z jakiegoś powodu nie powinien lub nie może zostać użyty . Nawet wtedy większość komentarza powinna być wyjaśnieniem, a nie kodem zastępczym. Może to być błąd lub funkcja języka, który nie jest jeszcze uważany za stabilny. Może to wyglądać mniej więcej tak:
W tym przypadku praca została już wykonana, ale nie możesz jeszcze z niej skorzystać, więc usunięcie jej oznacza, że ktoś będzie musiał ją później odkryć. To samo dotyczy rozwiązań nieoptymalnych, które mogą wydawać się lepsze na pierwszy rzut oka lub świadomych kompromisów z podobnymi rozwiązaniami .
Uwaga: nie zaśmiecaj swojego kodu alternatywnymi rozwiązaniami. Każde zadanie można wykonać na nieskończenie wiele różnych sposobów, a eksplorowanie tej przestrzeni przez długi czas przy każdej zmianie nie jest opłacalne. Recenzje kodu mogą być dobrym miejscem do odkrycia takich brakujących komentarzy, gdy twój kolega sugeruje ulepszenie, które już odkryłeś, że jest nieoptymalne.
źródło
frobnicate(bar)
, aby nikt nie przyszedł i nie próbował naprawić „nieeleganckiego” kodu. Więc pokazujesz im, że wiesz, że w idealnym świecie tafrobnicate
funkcja byłaby właściwą drogą, ale wiesz z bolesnego doświadczenia, że to nie działa poprawnie. Może nie być żadnych oczekiwań, że strona trzecia nawet uzna to za błąd, a tym bardziej nie warto go naprawiać; nadal musisz zostawić komentarz przyszłym programistom (w tym sobie) na temat tego, dlaczego nie przyjąłeś oczywistego podejścia.Hmm, przeczytałem to pytanie nieco inaczej niż Robert, który poprawnie twierdzi, że skomentowany kod powinien zostać usunięty.
Jeśli jednak szukasz konwencji oznaczania kodu do późniejszego usunięcia, moim ulubionym jest:
//b = false; //TODO: remove
//TODO:
Komentarze flag IDE lub można się ich nauczyć. Jeśli nie, zwykle jest to ciąg do przeszukiwania. Najlepiej postępować zgodnie z konwencją ustanowioną przez sklep, ponieważ można to zrobić na kilka sposobów. Każda baza kodu powinna robić to w jeden sposób. Umożliwia wyszukiwanie.Bez tego znaku zautomatyzowanym sposobem na to jest kompilator. Jeśli usunięcie komentarza powoduje powstanie kodu, który się kompiluje, kod musi zostać skomentowany. Pisanie wtyczki IDE, która sprawdza, co nie byłoby trudne. Ale pozostawi błędny kod z komentarzem.
Dlatego lepiej po prostu oznaczyć kod z komentarzem jako kod w momencie, gdy go skomentujesz. Dzięki temu możesz pracować nieniszcząco, jednocześnie decydując, czy naprawdę chcesz tego odejść. Ponieważ wszyscy zostają nam przerwani i jesteśmy nieco zapomniani, nie zdziw się, jeśli niektóre linie zostaną sprawdzone w tym stanie. Jeśli tak, to fajnie, że są przynajmniej wyraźnie oznaczone i można je wyszukiwać. W przeszłości pomogły mi makra klawiaturowe. Trudno jest w tym przerwać, jeśli możesz to zrobić jednym naciśnięciem klawisza.
Możesz to zrobić, jeśli chodzi o zapisywanie znaku w ciągłych testach integracyjnych. Ups, próbuję ponownie sprawdzić w znakomitych TODO.
źródło
double buffer (flip on)
-> prototyp C czy ultra-krótki angielski? nie można powiedzieć bez kontekstu, niepoprawna cała konstrukcja w żadnym języku. Niektóre fałszywe pozytywy i negatywy są nieuniknione, gdy komentarze z natury nie ograniczają formy treści w obu kierunkach.Używam dyrektyw preprocesora do usuwania kodu, a nie komentarzy w ogóle:
To sprawia, że bardzo łatwo jest szukać, a mój wyróżnik składni traktuje to jako komentarz. Mogę nawet zwinąć go w jedną linię:
#if FALSE(...)
Możesz rozwinąć ten pomysł, aby mieć kilka opcji:
I sprawdzanie błędów w czasie kompilacji:
Oczywiście nie chcesz przesadzać, albo trudno jest powiedzieć, co się kompiluje, a co nie. Ale masz pomysł, i tak samo jest w przypadku skomentowanego kodu ... pod warunkiem, że używasz go tylko statycznie. Jeśli twoje warunki są dynamiczne, jest gorzej.
Aby ustalić, która jest w istniejącej bazie kodu, która w ogóle nie brała pod uwagę tego problemu, nie sądzę, że istnieje uniwersalne rozwiązanie. Musisz sam znaleźć wzorce i prawdopodobnie kodować wyrażenie regularne, aby je znaleźć.
źródło
javascript
. Możesz wykonać wstępne przetwarzanie, ale rozszerzy ono możliwości systemu kompilacji i jest również niestandardowe. Jeśli nie masz systemu kompilacji lub system kompilacji w ogóle nie obsługuje analizowania i wykonywania kodu, nie będziesz w stanie zaimplementować tego rozwiązania. Wreszcie, nawet nie rozwiązuje pytania - skomentowany kod nie jest ściśle równoważny kodowi, który jest aktywowany warunkowo. Może to być pozostałość, której nie należy włączać.Zgadzam się z odpowiedzią stwierdzającą, że stary kod powinien zostać usunięty, a nie skomentowany tam, gdzie to możliwe, jednak przestrzegałem konwencji w tych kilku przypadkach, w których potrzebny jest kod z komentarzem.
(Moja podstawa to C #, ale można to zastosować w dowolnym języku składni C, np. Java)
źródło
//
do pierwszej kolumny, a ponieważ praktycznie cały kod jest wcięty, praktycznie zawsze jest tak, że komentarz zaczyna się od niektórych zakładek. Normalne komentarze nie otrzymują ode mnie wiodącej przestrzeni, chyba że w pobliżu są już inne komentarze z wiodącą przestrzenią. Tak więc twoja metoda zawiodłaby śmiertelnie na komentarzach, które stworzyłem, a każda metoda zaprojektowana w celu rozpoznania moich wzorców komentarzy zawiodłaby na twojej.Wciąż interpretuję to pytanie, myśląc, że chcesz znaleźć skomentowany kod.
Kod w stylu C musi zawierać w sobie średniki, podczas gdy w komentarzach raczej nie będzie w nich średników. W przypadku kodu z komentarzem w jednym wierszu można użyć tego wyrażenia regularnego:
Może to być kod skomentowany z wielu wierszy
Uwaga: Visual Studio jest nieco osobliwy w przypadku podziałów linii w wyrażeniach regularnych, nie liczą się one jako białe znaki, musisz podać wyraźne \ n.
źródło
Jeśli używasz edytora z kompilatorem działającym w tle (takim jak Xcode i Clang), możesz po prostu spróbować skompilować tekst komentarza. Na przykład „zwięzły opis” podaje błędy, „b = fałsz;” nie. Możesz wtedy użyć innego podświetlenia składni.
Prostszą metodą byłaby wtyczka IDE, która korzysta z niektórych heurystyk, takich jak wiele słów w wierszu innych niż słowa kluczowe, które wskazują na komentarze, dopasowane kręcone, punktowane do kodu itp.
źródło
Inne odpowiedzi dotyczyły odmian tematu „nie komentuj kodu”. Ale czasami nadal chcesz go mieć w celach informacyjnych.
Jeśli naprawdę potrzebujesz kodu, aby pozostać w pobliżu, lepszym rozwiązaniem jest otoczyć go kodem „#if 0 ... #endif”, najlepiej z komentarzem wyjaśniającym dlaczego. Jest to zalecana strategia różnych standardów kodowania, w tym MISRA.
źródło
Proste, przynajmniej dla mnie - i w C / C ++. Komentarze zawarte w / * * / mają charakter informacyjny. Kod testowy, który jest tymczasowo usuwany, jest komentowany za pomocą wiodącego //.
I jest dobry powód, aby zostawić kod testowy w pliku, ale skomentował, przynajmniej w rodzaju pracy, którą wykonuję. Wcześniej czy później ktoś będzie chciał wprowadzić zmiany, które będą wymagać tego kodu. Odkomentowanie bloku wymaga jednego polecenia edytora, podobnie jak ponowne komentowanie go po zakończeniu.
źródło
#ifdef __DEBUG ... #endif
dowolna niestandardowa definicja, której chcesz użyć.__DEBUG
jest miło, ponieważ często wystarczy zmienić konfigurację projektu, aby go uzyskać. Ale większość IDE pozwala również definiować własne konfiguracje, które mogą dać ci wszystko w tym miejscu.printf
/cout
lub podobnego do poprawnego napisania nowo napisanego kodu (co muszę przyznać, że robiłem to w przeszłości), pozostawienie ich tam naprawdę nie jest zbyt skuteczne. Jeśli ktoś chce wprowadzić zmiany i wie, o których zmiennych potrzebuje informacji, szybko i łatwo napisać odprintf
nowa, natomiast jeśli ten deweloper nie wie, co jest potrzebne i po prostu cofnie komentarz wszystkich tychprintf
stwierdzeń, wówczas ogromny pokos tekstu w terminal prawdopodobnie też im nie pomoże.