Komentowanie kodu tak aby go nie zaciemniać

pytanie zadane 4 października 2017 w PHP przez kevin Mądrala (5,010 p.)

Witam!

W jaki sposób przejrzyście komentować kod tak aby nie zaciemniać instrukcji ? Wiadome jest że nad funkcją wypada wstawić komentarz na temat tego co robi, co zwraca i co przyjmuje np.

//
//   Funkcja łączy dwa napisy
//
//   Parametry:
//      $s1 - string
//      $s2 - string
//
//   Zwraca:
//      string
function join( $s1, $s2) {
    return $s1.$s2;
}

Proszę się nie śmiać to dla przykładu. Ale jak widać coś takiego też potrafi zaciemnić kod...

Pytanie głównie kieruję jak komentować reakcje np. na pobranie konkretnego wyniku z bazy np. konto jest nie aktywne, nie istnieje takie konto, nic nie stoi na przeszkodzie aby się zalogować. Przykład:

if($stmt->rowCount() > 0)
{
     $acc = $stmt->fetch(PDO::FETCH_ASSOC);

     if( $acc['activated_daytime'] == null) {
  
             //
             // Tutaj wypada postawić komentarz że konto jest nieaktywne 
             //

            // 
            // zakończenie działania skryptu z powodu nieaktywnego konta
     }
    else
    {
            // -------------------------------------------------------------
            // Można się zalogować
    }
}

// Konto nie istnieje
exit();

To trochę dziwne pytanie bo może zależy i od gustów. Ale czy jest jakaś jednolita metoda dla PHP która usala jasne reguły od komentowania tego typu sytuacji ?

komentarz 4 października 2017 przez Bany Nowicjusz (130 p.)

Wiadome jest że nad funkcją wypada wstawić komentarz na temat tego co robi, co zwraca i co przyjmuje np.

Przepraszam, ale czy jest to faktycznie tak wiadome? Spotkałem się w pewnej publikacji z twierdzeniem, że taka praktyka zaśmieca kod. Co dana funkcja wykonuje, programista wie lub powinien wiedzieć. Sugerowano by komentarzami opisywać DLACZEGO wybrało się takie rozwiązanie oraz inne informacje, jeśli przyjdzie pracować z kodem komuś innemu.

komentarz 4 października 2017 przez event15 Szeryf (93,790 p.)

Oczywiście że nad metodami nie wstawiamy komentarzy - pomijając te dokumentacyjne. Aczkolwiek takie komentarze zawsze pozostają w tyle jeśli chodzi o kod. Ktoś zmieni kod a nie zmieni komentarza i nagle nikt nic nie wie.

2 odpowiedzi

odpowiedź 4 października 2017 przez Ehlert Ekspert (212,670 p.)
edycja 4 października 2017 przez Ehlert

/* 
 * Opis funkcji co robi
 *
 * @param int $param opisz parametr i wymyśl lepszą nazwę
 * @param \PDO $con to samo
 * 
 * @return int opisz może
 * 
 * @access private
 *
 * @throw RuntimeException daj info kiedy
 */
private function documentedFoo(int $param, \PDO $con)
{
//
}

Krótko mówiąc PhpDoc.

Prawdę mówiąc czysty kod będący ciałem funkcji sam się komentuje. Twój drugi przykład taki nie jest. Skąd mam wiedzieć, że chodzi Ci o Usera.

$user = $userRepository->getUserById($id);

if (null === $user || !($user instanceof User)) {
	throw...;
}

$user->createChatBan();

Nie trzeba elsów zbędnych wcięć itp. Czytasz, nie wiesz jak to działa (jest dokumentacja) i rozumiesz zamysł.

komentarz 4 października 2017 przez maly Nałogowiec (37,190 p.)

Ten kod też nie jest zbyt dobry, wygląda jakby funkcja getUserById mogła zwrócić nie tylko null(co już jest "nieładne") i klasę User, ale także jakiś inny bliżej nie określony typ.

komentarz 4 października 2017 przez event15 Szeryf (93,790 p.)

Poza tym nie powinno się do konkretnego typu sprawdzać za pomocą instanceof, tylko do jego interfejsu. Inna sprawa, że jest już PHP7, który pozwala dbać o takie typy bez wykorzystania instanceofów.

Czasem też jest lepiej zwrócic NullObject implementujący dany interfejs i obsługujący w odpowiedni sposób ten przypadek niż zrzucienie po prostu nulla.