Czy są jakieś badania empiryczne na temat wpływu komentowania kodu źródłowego na jakość oprogramowania, łatwość konserwacji i produktywność programistów? [Zamknięte]

11

Jestem zwolennikiem komentowania kodu źródłowego i dokumentowania oprogramowania. Z mojego osobistego doświadczenia i obserwacji wynika, że ​​praca nad kodem źródłowym, który jest rygorystycznie komentowany, pomogła mi na różne sposoby, kiedy musiałem rozwijać oprogramowanie lub utrzymywać je.

Jednak istnieje inny obóz, który mówi, że komentowanie jest ostatecznie bezwartościowe lub jego wartość jest wątpliwa. Wielu zwolenników kodowania bez komentowania twierdzi, że:

  • Jeśli fragment kodu jest dobrze napisany, jest zrozumiały i dlatego nie wymaga komentarza
  • Jeśli fragment kodu nie wymaga wyjaśnień, przeredaguj go i spraw, aby nie wymagał komentarzy
  • Twój pakiet testowy to twoja dokumentacja na żywo
  • Z biegiem czasu kod i komentarze nie są zsynchronizowane i staje się kolejnym źródłem problemów
  • Agile twierdzi, że działający kod jest ważniejszy niż stosy dokumentacji, więc możemy bezpiecznie ignorować pisanie komentarzy

Dla mnie to tylko dogmat. Ponownie, moją osobistą obserwacją było to, że oprogramowanie napisane przez zespoły inteligentnych i doświadczonych programistów ostatecznie kończy się znaczną ilością kodu, który nie jest oczywisty.

Ponownie, Java API, Cocoa API, Android API itp. Pokazują, że jeśli chcesz pisać i utrzymywać dokumentację wysokiej jakości, jest to możliwe.

Powiedziawszy to wszystko, rozmowy na temat zalet i wad dokumentacji oraz komentowanie kodu źródłowego oparte na osobistych przekonaniach zwykle nie kończą się dobrze i nie prowadzą do satysfakcjonujących wniosków.

Jako taki szukam prac naukowych i badań empirycznych na temat wpływu dokumentacji oprogramowania, zwłaszcza komentowania kodu źródłowego, jego jakości i łatwości konserwacji, a także jego wpływu na produktywność zespołu.

Czy natknąłeś się na takie artykuły i jaki był ich wynik?

productivity documentation code-quality maintainability engineering Behrang Saeedzadeh
źródło
2
Myślę, że i tak jest to interesujące pytanie, ale nie jestem zaskoczony, że może zostać tutaj zamknięte. Dlatego też opublikowałem to na Quora.
Behrang Saeedzadeh
4
@gnat - Wydaje mi się, że „Jakie badania przeprowadzono w tym aspekcie rozwoju oprogramowania?” to raczej inne pytanie niż prośby „proszę o książki na dany temat”, które nie są mile widziane.
Josh Kelley,
1
Już z lektury tytułu: Nie ma badań empirycznych na temat wpływu czegokolwiek na jakość. Gdyby tak było, ta strona nie istniałaby.
Euforia
2
@Euforyczne twoje dwa stwierdzenia są ze sobą sprzeczne. Jeśli zignorujemy „szalony” 30-letni dokument, nie będzie konfliktu. W każdym razie nie powinniśmy ignorować ustaleń tylko dlatego, że są stare, ale krytycznie oceniają ich stosunek do współczesnej pracy (podobnie jak w przypadku nowych wyników).
3
@Euphoric Chciałbym, żebyś opublikował to jako odpowiedź, abym mógł zagłosować za twój całkowity brak badań w twoim twierdzeniu o kocu. Istnieje mnóstwo artykułów i badań, empirycznych i innych, na temat wpływu różnych technik na jakość oprogramowania. Czy studiowałeś coś o inżynierii oprogramowania?
Andres F.,

Odpowiedzi:

9

W „Wpływ modularyzacji i komentarzy na zrozumienie programu” (1981) Woodfield, Dunsmore i Shen stwierdzili, że „podmioty, których programy zawierały komentarze, były w stanie odpowiedzieć na więcej pytań niż osoby bez komentarzy”.

Jednak w „Learning a Metric for Readable Code” (2010) Raymond PL Buse i Westley Weimer stwierdzili, że komentarze mają ograniczony wpływ na czytelność i jakość:

Z streszczenia:

Konstruujemy automatyczną miarę czytelności i ... pokazujemy, że ta metryka silnie koreluje z trzema miarami jakości oprogramowania: zmianami kodu, automatycznymi raportami błędów i komunikatami błędów ... Nasze dane sugerują, że komentarze same w sobie są mniej ważne niż proste puste wiersze do lokalnych ocen czytelności.

Od strony 12:

Stwierdziliśmy, że komentarze są tylko umiarkowanie dobrze skorelowane z pojęciem czytelności naszych adnotatorów (33% mocy względnej). Jednym z wniosków może być to, że chociaż komentarze mogą poprawić czytelność, zwykle są one używane w segmentach kodu, które zaczynały się mniej czytelnie: komentarz i nieczytelny kod skutecznie równoważą się. Wydaje się, że efekt netto jest taki, że komentarze nie zawsze same w sobie wskazują na wysoką lub niską czytelność.

Należy pamiętać, że zwolennicy „kodowania bez komentowania” nie twierdzą, że kod bez komentarzy jest lepszy niż kod z komentarzami. Twierdzą, że określony styl kodu bez komentarzy - taki, który wyodrębnia kod do metod z samoopisującymi nazwami, taki, który wprowadza zmienne wyjaśniające , taki, który ma dobry zestaw testów - jest lepszy niż kod, który nie robi tych rzeczy ale ma komentarze. Może to utrudnić zastosowanie wszelkich przeprowadzonych badań.

Josh Kelley
źródło
1
Artykuł Woodfielda i wsp. Dotyczy określonej różnorodności komentarzy, mniej więcej równoważnych z tym, co teraz nazwano by Javadoc: „W szczególności badanie to próbuje ustalić, czy krótkie komentarze wstawione tuż przed modułem logicznym mogą pomóc w zrozumieniu przez krótkie opisanie funkcji modułu logicznego i pomoc w zdefiniowaniu granic modułu logicznego. ”
W tym czasie powinienem był dodać: to nie znaczy, że nie ma wartości, w rzeczywistości jest to interesujące i dobrze skonstruowane badanie. Pomyślałem, że trzeba powiedzieć, że nie biorą pod uwagę wszystkich komentarzy.