Komentarze drugiej i trzeciej osoby?

Question

Czy piszesz komentarze na 2. lub 3. miejscu?

// go somewhere and do something (2nd person comment) 

lub

// goes somewhere and does something (3rd person comment) 

Answer 1

Zdecydowanie 3 osoba styl.

Answer 2

często wydają się mówić styl Lekarz:

// Now we take $x and check whether it's valid for this pass 

Answer 3

Jedna pomocna wskazówka: spróbuj zachować każdy komentarz jako samowystarczalny, jak to możliwe. Na przykład, taka forma:

// First, mumble the frabbitz. 

blah blah 

// Second, foobar the quux 

blah blah 

jest to miłe narracja, ale utrudnia edycji kodu, ponieważ części „pierwszy” i „drugi” może stać się nieprawidłowe. W końcu nie dodają tak wiele do komentarzy, ale powodują, że są ze sobą powiązane w delikatny sposób.

Answer 4

czasami mówić w 1 osoby, jak to

/* 
Usage: 
set_position(0.5, 0.5); // im in the center 
set_position(0.0, 1.0); // im in the lower,left corner 
*/ 

Answer 5

To może zależeć od tego, jak wiele osób edycji kodu i do jakich celów. W moim własnym kodzie (który mimo to jest dostępny dla opinii publicznej) mogę dodawać komentarze osobiste, być może używając "ja". We wspólnym projekcie komentarze powinny mieć wspólny styl, a "ja" może być nie na miejscu.

Należy zauważyć, że komentarze są delikatne, a wiele nowoczesnych autorytetów (np. "Czysty kod") sugeruje, że funkcje i pola powinny zawierać znaczące nazwy. Ale, oczywiście, istnieje wiele miejsc, w których komentarze wyjaśniające są nadal ważne.

Answer 6

Mój pogląd jest taki, że powinieneś po prostu użyć dowolnego stylu, w którym czujesz się najlepiej.

Wbudowane komentarze powinny być czytane przez Ciebie i innych programistów, którzy próbują zrozumieć szczegóły implementacji Twojego kodu. Tak długo, jak są jasne i zrozumiałe, ma to znaczenie, jeśli styl jest nieco nietypowy, gramatyka jest nieco słaba, lub istnieje kilka błędów pisowni. Ludzie, którzy ją czytają, powinni mieć na względzie takie rzeczy.

Komentarze wyodrębnione do dokumentacji interfejsu API zasługują na nieco większą uwagę na styl, gramatykę i pisownię. Ale nawet tutaj dokładność i kompletność są o wiele ważniejsze.