Czy istnieje metoda odróżnienia komentarzy informacyjnych od skomentowanego kodu?

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:

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

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:

# TODO: Replace with `foo = frobnicate(bar)` once <link.to/bug> is fixed
foo = [some complex workaround]

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.

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.

szybko parsuj który jest który?

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.

Używam dyrektyw preprocesora do usuwania kodu, a nie komentarzy w ogóle:

//comment
active_code();
#if FALSE
inactive_code();
#endif

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:

#if OPTION == 0
code_for_option_0();
#elif OPTION == 1
code_for_option_1();
#else
code_for_all_other_options();
#endif

I sprawdzanie błędów w czasie kompilacji:

#if FOO >= 5
#error FOO should be less than 5!
#endif

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

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)

// An explanatory comment has a space between the comment marker and the content.

// The following lines are commented out code so do not have the space (except where indented).
//var a = something();
//if(a==2) {
//   doSomethingElse();
//}

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:

\s*\/\/[\s\S]*;

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.

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.

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.

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.