Jak komentować kod i nazywać zmienne?

 Zauważyłem że w wielu poradnikach, nie jest pokazywane jedne z ważniejszych, jeśli nie najważniejsze cechy czytelnego kodu, a właściwie komentarze i nazwy zmiennych.
W efekcie wielu początkujących programistów nie zwraca na to uwagi.

Adres: http://demotywatory.pl//uploads/201108/1314126951_by_Aventador_600.jpg

Wiele osób twierdzi, że skoro nie piszą programów do innych, to nie muszą dbać o czytelność, ponieważ sami po sobie się doczytają.
To prawda, pod warunkiem że mamy bardzo mały projekt, w którym często coś zmieniamy (znamy całość na pamięć, przez cały czas). Jednak co jeśli nagle zechcecie napisać coś większego? Albo gorzej, postanowicie zrobić projekt dla kogoś. W takiej sytuacji nie będziecie w stanie przestawić się z pisania brzydkiego i niejasnego kodu, na czytelny i zrozumiały dla wszystkich - tą umiejętność trzeba szlifować cały czas, przy każdym projekcie.

Pokaże wam przykładowy kod, który napisałem jakiś czas temu.
Cały projekt był pisany dość czytelnie, poza jednym skryptem, który zlekceważyłem i nie zwiększyłem mu czytelności, po tym jak zaczął prawidłowo działać.
Skrypt był dość mały (stronicowanie na blogu), jednak posiadał kilka skomplikowanych elementów, przez które wczoraj musiałem dłuższy czas się zastanowić, jak to działa i czy na pewno tak powinno to wyglądać

Przepraszam za mój angielski (jeszcze się uczę)

Oto lista poważniejszych zmian, jakie musiałem przeprowadzić, żeby skrypt stał się czytelny

• Usunięcie zbędnej instrukcji if na początku
• Dodanie komentarzy do każdej sekcji kodu
• Nazwy zmiennych, przez które nie musimy się domyślać co kiedy się dzieje

Innym problemem jaki widać u wielu początkujących, jest złe nazywanie zmiennych.
Nie mam tu na myśli podstawowych błędów, np pisania ich nazw od dużych liter, czy nazywania zmiennych jedną literą (za wyjątkiem pętli for), tylko zbyt ogólne nazwy.
Przeanalizujcie nazwy zmiennych w starej wersji kodu, czy możecie rozszyfrować do czego one służą, bez spojrzenia na ich mechanikę? W części jest to rzeczywiście możliwe, jednak my chcemy mieć taką pewność w przypadku wszystkich zmiennych, dlatego warto nazywać je w nieco bardziej rozbudowany sposób.
Kompilator ignoruje długości nazw zmiennych, traktuje je jako identyfikatory, więc w programie nie ma znaczenia czy nasze zmienne będą jednoliterowe, czy będą składały się z dokładnych opisów - program będzie działał i ważył identycznie... w przeciwieństwie do komfortu naszego i wszystkich osób, które czytają nasz kod.