Skomentuj styl: Imperative lub osoba trzecia

Question

Mam pytanie dotyczące programowania i języka angielskiego zarówno: Czy używać trzeciej osoby lub imperatywu podczas komentowania pojedynczych linii kodu. Załóżmy następujący wiersz kodu w języku imperatyw, który powinien być komentuje:

object.doSomething(); 

Moje podejście do komentowania tej linii byłoby umieścić komentarz za nim za pomocą osoby trzeciej jak byłoby to zwykłe zdanie po angielsku zawierający linię jako przedmiotu:

object.doSomething(); // does (referencing to the line of code) some action 

Ale ponieważ jesteśmy w języku bezwzględnej, a więc faktycznie „dowodzący” komputer, można było nawet myśleć o umieszczenie komentarza przed kodem i korzystania imperatyw:

//Do some action: 
object.doSomething(); 

Jest to przydatne nawet, gdy trzeba skomentować wiele linii powiązanych ze sobą.

Ja osobiście preferuję pierwszy styl, ale często nie mam pewności, jakiego stylu użyć. Byłoby wspaniale, gdyby niektórzy mogli napisać tutaj swoje osobiste doświadczenia.

Answer 1

Pierwsze podejście to z pewnością bardziej odpowiednia metoda komentowania, ponieważ ludzie będą czytać Twoje komentarze, dlatego ważne jest, aby były one tak łatwe do odczytania, jak to tylko możliwe. //Do something brzmi, jakbyś mówił do komputera, a nie wyjaśniał, co robi kod.

Answer 2

Oracle oficjalne stany prowadzące styl:

Zastosowanie 3 osoby (opisowa) nie 2. osoba (nakazowe). Opis znajduje się w trzeciej osobie o charakterze deklaratywnym, a nie drugim.

Pobiera etykietę. (preferowane)

Uzyskaj etykietę. (unik)

Przewodnik po stylu Oracle można znaleźć here.