Dobry styl pisania kodu

Dzień doberek.
Był temat o udziwnieniach i ogólnie sporo tematów przewinęło się o stylu pisania kodu. Natomiast nigdzie tak naprawdę nie ma wypunktowane "jak należy pisać". Oczywiście jest to zrozumiałe, ponieważ po 1.) "szkół" uczących jak pisać jest wiele. Po 2.) Wiele też zależy od języka, chociażby jego składni no i po 3.) Każdy z czasem nabywa swój własny styl, który według niego jest najlepszy.

Chciałbym jednak w tym topicu zniszczyć te wszystkie granice i stworzyć uniwersalny topic w, którym bardziej doświadczeni koderzy podzielą się - najlepiej od myślników - ze swoimi przemyśleniami, jak pisać by było ładnie.

Czemu taki topic byłby fajny i uniwersalny mówić nie muszę, chciałbym jednak uniknąć tutaj JEDYNIE do odsyłania do książek. Oczywiście napomknąć na końcu posta np jak najbardziej można, wręcz zalecane jest, chodzi o to by nie tworzyć jakiegoś strasznego offtopa tutaj. Taki wątek będzie fajny dla każdego kogo interesuje ładny styl pisania.

Można powiedzieć, że chciałbym tu zrobić takie małe FAQ jak pisać kod. Oczywiście prosząc też przy okazji o nie negowanie np czyichś obserwacji. Np user A uważa, że lepiej robić tak i tak, natomiast user B absolutnie to odradza. Taka sytuacja również potrafi dać niezły obraz całości, więc i takie sytuacje będą przydatne.

No to cóż. Może zacznijmy :)?

jezeli o C/C++ chodzi to Mozilla Coding Guide i standard MISRA C

http://davetron5000.github.com/scala-style/index.html

Jeżeli chodzi o Delphi, to piszę tak:

Procedure InicjujDane;                                  // Polskie nazwy procedur i funkcji (rzadko daję angielskie)
Type TMojTyp = Record                                   // Zaczynamy wielką literą
                Zmienna, InnaZmienna: Integer;          // Ewentualnie komentarz
                CiekawaZmienna      : String;           // No comment :-)
               End;                                     // End też wielką literą
Var Zmienna, InnaZmienna: Integer;                      // Komentarz
    CiekawaZmienna      : String;                       // Inny komentarz
    MojTyp              : TMojTyp;                      // Całkiem inny komentarz
    I                   : Integer;                      // I - zazwyczaj do pętli
Begin                                                   // BEGIN również wielką literą
 MojTyp.Zmienna := 25;                                  // Pojedyncze wcięcie
 if (MojTyp.CiekawaZmienna = 'Welcome') Then            // Enter po THEN
  MojTyp.Zmienna := InnaZmienna;                        // Znowu wcięcie
 if ((MojTyp.InnaZmienna Mod MojTyp.Zmienna) = 25) Then // Przy MOD - podwójne nawiasy
  MojTyp.CiekawaZmienna := 'Mod OK';                    // Przypisanie
 For I := 0 To MojTyp.Zmienna Do                        // Enter po DO
 Begin                                                  // BEGIN wielką literą
  Inc(MojTyp.Zmienna);                                  // Inc/Dec --> zamiast MojTyp.Zmienna := MojTyp.Zmienna + 1
 End;                                                   // End również wielką
 Repeat                                                 // Pętla REPEAT
  Dec(MojTyp.Zmienna);                                  // Wcięcie pojedyncze
 Until (MojTyp.Zmienna < 0);                            // Tutaj też lubię wstawiać nawiasy ;-)
End;                                                    // Końcowe END również z Wielkiej Litery :D

Nie lubię za bardzo robić podwójnych wcięć ;-)

Jakoś sam z siebie wyszedł taki styl pisania. Wg.mnie, nie jest on najgorszy. Prawie zawsze go używam.
Jak dla mnie, to ciekawym pomysłem jest wstawianie całości wyrażenia z IF'ów do nawiasów.

Patryk27 napisał(a)

Procedure InicjujDane;                                  // Polskie nazwy procedur i funkcji (rzadko daję angielskie)

Zgubiłeś mnie tutaj.

1. Jeśli chodzi o dokumentację i komentarze to ja wolę używać długich nazw zmiennych, klas i funkcji, które dobrze określają ich znaczenie, zamiast używać krótkich nazw i komentować ich znaczenie co chwilę. Poza tym długie nazwy pomagają w przypomnieniu sobie działania programu jeśli zaglądamy do niego po długiej przerwie.

2. Jeżeli używam już polskich nazw pól w kodzie to lubię też używać ogonków - w końcu cała platforma Java ma obsługę Unicode.

3. Grupuję kod w małe bloczki, tzn jeżeli funkcja jest długa to oddzielam poszczególne grupy instrukcji pustymi liniami. Grupa instrukcji jest odpowiedzialna za przygotowanie jakiegoś pojedynczego, niezależnego obiektu lub małego grafu obiektów.

4. W Javie i C++ klamry walę po wszystkich ifach, whilach itp Dzięki temu jak szybko przeglądam kod to widzę od razu czy mi się przepływ kodu rozjeżdża, czy tylko linia była za długa i musiała zostać złamana.

5. Ubolewam nad faktem, że kod to zwykły, czysty tekst. Chciałbym, aby edytory pokazywały kod w bardziej zwięzły i szybciej przyswajalny sposób, np jeżeli liczę sumę silnii, to zamiast oglądać: "(a to b).map(_!).sum", chciałbym widzieć zapis matematyczny z sigmą. Ubolewam też nad faktem, że nie ma systemów tłumaczeń kodu i dokumentacji - świetnie by było jeżeli można by przetłumaczyć nazwy funkcji i treść dokumentacji do dowolnego języka, a potem w IDE sobie wybrać język, dopasowany do języka całego projektu.

Zainspirowany stylem pisania kodu Patryka27, stworzyłem coś jeszcze lepszego. Teraz komentuję każdy token!!! Zobaczcie na mój cholernie łatwy do zrozumienia kod programu wypisującego HelloWorld!.

public          // oto przepiękny modyfikator nasze klasy, będzie ona publiczna
class           // deklarujemy sobie klasę
Main            // będzie się nazywać Main
{               // o! zaczyna się!
    public      // kolejny cudowny modyfikator, tym razem dla metody, która też będzie publiczna
    static      // o i jeszcze jeden, mówiący, że nasza metoda jest statyczna, czyli nie potrzebuje obiektu
    void        // nasza metoda nie będzie nic zwracać, więc Javie trzeba to uświadomić
    main        // metoda będzie się nazywać main
    (           // o! zaczynają się parametry metody
    String      // pierwszy parametr przyjmuje coś związanego z łańcuchami znaków
    [           // o to jest nawet tablica
    ]           // i to niewiadomego w czasie kompilacji rozmiaru
    args        // nazywa się ona args
    )           // o! zakończyły się parametry
    {           // teraz klamerka oznaczająca początek ciała metody
        System  // System to klasa trzymająca sporo przydatnych funkcji i pól
        .       // wybierzemy sobie jedno
        out     // out to stanardowe wyjście
        .       // wywołamy sobie na nim metodę...
        println // ... o nazwie println, czyli będziemy wypisywać linię
        (       // tu zaczynają się parametry
        "Hello World!"  // pierwszym parametrem jest sławetny napis "Hello World!"
        )       // o! parametry się już skończyły! widzicie jak mało potrzeba?
        ;       // średnik kończący instrukcję, bo Java sama by się nie połapała
    }           // o! a tu klamra kończąca ciało funkcji, jak widać zapomnieliśmy returna
}               // no a tu niestety nasza klasa się kończy

Od razu widać co się dzieje, nie?

chciałbym widzieć zapis matematyczny z sigmą
skoro lubisz nazwy funkcji z ogonkami, to stwórz sobie funkcję Σ() i będziesz miał.

@Wibowit:
Wydaje mi się, że @Patryk27 wstawił te komentarza na potrzeby zdefiniowania standardu. I że normalnie takich... nadmiarowych komentarzy nie używa.

Osobna sprawa, że takie komentarze nawet tutaj są zbędne. Całkowicie bezsensowne jest pisanie "Pętla repeat" przy... pętli repeat. Niezależnie od tego, czy pisze się to w kodzie produkcyjnym, czy w tym wątku. Ale tutaj można to zrobić bezwiednie, z marszu, kontynuując inne wyjaśnienia (bo może jakieś tam komentarze mają tu swój cel). W kodzie jest to niedozwolone i mam nadzieję, że każdy się nad tym zastanowi i zda sobie z tego sprawę. Komentarz Inkrementacja i przy linijce i++ to sztandarowy przykład, jak NIE należy pisać komentarzy -- obecny w paru książkach ;).

imho jak cos w metodzie / funkcji wymaga komentarza to albo jest z tym kawalkiem cos nie tak albo jest to hack, natomiast co do dokumentowania kodu to jedynie naglowki metod/funkcji z opisem parametrow

Już kiedyś chyba był taki temat.

W każdym razie - nazwy zmiennych, wcięcia, komentarze, entery - to wszystko nie ma najmniejszego znaczenia (albo powiem inaczej: ma takie znaczenie jak interpunkcja w książce).

Co ma znaczenia, to to, czy kod (aplikacja) jest dobrze zaprojektowany - wg zasad DRY, KISS, SOLID - oraz oczywiście wzorców projektowych. To czyni kod dobrym, a nie tam czy robimy tu wcięcie takie czy inne.

no chyba, że miałeś na myśli te duże "F" przy for-ach itd

Na przykład. Mam tendencję do pisania słów kluczowych małymi literami, podobnie jak typy proste (integer) i podstawowe funkcje (writeln, inttostr).
Ale z pewnymi wyjątkami:

procedure foobar;
var
  x:integer;
begin
  x:=3;
end;

VAR                            // var globalny - dużymi
  i:integer;
BEGIN                        // główny begin - dużymi
  writeln('hello world!');  // średnik przed end jest opcjonalny. ja go zawsze stawiam.
END.

podobnie podstawowa struktura unitu:

UNIT jakis;

INTERFACE

   ...

IMPLEMENTATION

   ...

END.

z innych rzeczy: if

if warunek1 then foobar;

if warunek2 then
begin
  foo;
  bar;
end;

if warunek3 then
begin
  foo;
  bar;
end
else baz;

if warunek4 then
begin
  foo;
  bar;
end else begin
  baz;
  qux;
end;

// ale dla estetyki, czasami przenoszę then do następnej linijki:
if warunek5
  then foo
  else bar;