Bardzo ważną rzeczą w programowaniu zespołowym jest standard kodowania, czyli mówiąc inaczej - standard zapisu składni języka programowania. Chodzi tutaj o wytyczne jakimi powinni kierować się programiści piszący kod w Coyote. Ponieważ Coyote jest pisany w języku PHP oraz SQL, zasady przedstawione w niniejszym podręczniku tyczą się jedynie zasad zapisywania kodu w tych językach. Nie będziemy tutaj opisywać zasad zapisywania kodu HTML czy CSS.
Pytanie, po co ustalać reguły zapisywania składni? Wszystko po to, aby zwiększyć czytelność kodu, która jest bardzo istotna w projektach zespołowych. Nie wystarczy bowiem, aby kod był poprawny i nie zawierał błędów. Istotne jest to, aby kod był zapisany elegancko i wyraźnie, tak, aby inni nie mieli problemów z jego "rozczytaniem"
Zarówno w przypadku nazw funkcji, zmiennych czy stałych oraz klas stosujemy nazewnictwo angielskie. Np. Templates(), sql_query(), $topic_id. Nie deklaruj danych w ten sposób: Szablony(), zapytanie_sql(), $id_tematu.
Stosujemy zasadę, że wcięcia powinny wynosić 4 (cztery) spację; niedozwolone jest używanie tabulatorów.
<?
if ( $db->sql_query($sql) )
{
do_something();
}
?>
Tak więc podstawowe wcięcie o którego zaczynamy pierwszy blok instrukcji ma
wcięcie w wielkości 4 spacji. Do struktur kontrolnych zaliczamy instrukcję if(), while(), for() itp. Zalecane jest, aby w strukturach kontrolnych znalazla się jedna spacja po i przed nawiasem. Przykład:
if ( ( empty($cookie) ) && ( $id != 0 ) )
{
// jakieś zadanie
}
else
if ( empty($cookie) )
{
// zrób coś innego
}
Prosimy też o wpisywanie nawiasów klamrowych nawet wówczas, gdy nie są one potrzebne (np. gdy występuje jedynie jedna instrukcja). Zwiększa to czytelność kodu oraz eliminuje ew. błędy. Nie zapominamy oczywiście o czterech spacji wcięcia. Niedopuszczalna jest np. taka konstrukcja:
if ($x > 0) // coś tam
if ( $y > 1)
// coś tam
Nie ma żadnych żelaznych reguł regulujących sposób definicji funkcji. Zaleca się jednak, aby funkcje były pisane małymi literami bez stosowania 'stylu wielbłądziego'. Dopuszczalne jest użycie znaku _ - np.
function do_something()
{
// dobrze
}
function DoSomething()
{
// zle
}
Jest jedna zasada: im więcej komentarzy tym lepiej. Dodatkowo każdy plik PHP powinien mieć na górze na główek wyglądający mniej więcej tak:
/*************************************************************************
** Coyote Project
**
** $Id: coding-style.xml,v 1.1 2004/12/10 19:33:06 adam Exp $
**
** File name : login.php
** Started : 07.06.2004 r.
** License : GPL
**************************************************************************
*/
Na samej górze zostanie wstawiona informacje na temat wersji, użytkownika który wysłał plik. Informacja dodawana jest automatycznie przez CVS. Jeżeli chodzi o komentowanie kodu to używaj komentarzy w stylu C ( /* */ ) oraz //. Oba są OK - nie używaj natomiast standardu komentowania Perla (#). Komentarze piszemy w języku polskim.
Bardzo istotnym elementem w zbiorowych projektach jest naniesienie informacji o zmianach dokonanych przez danego dewelopera. W tym celu w projekcie obowiązuje tzw. plik ChangeLog, który jest umieszczony w głównym katalogu z kodami źródłowymi. Każda zmiana dokonana przez dewelopera powinna zostać opisana w tym pliku, tak, aby pozostali wiedzieli co zostało zmienione w danym dniu. Plik ChangeLog powinien mieć taką postać:
-------------------------
Coyote ChangeLog
-------------------------
$Id: coding-style.xml,v 1.1 2004/12/10 19:33:06 adam Exp $
$Source: /usr/cvs/coyote/docs/docsrc/coding-style.xml,v $
16.08.2004 <adam@boduch.net>
* poprawilem blad w plik db.php (nie zliczal ilosci zapytan kierowanych do bazy)
Zasada jest więc prosta. Najświeższe aktualności powinny być wpisywane na samej górze. Należy w tym miejscu dopisać datę poprawki, oraz w nawiasie - adres e-mail programisty. Następnie w wypunktowaniu należy umieścić krótki opis określający co i gdzie zostało zmienione. Miejscem do szerszego opisu poprawionego błędu jest skrypt (opis w formie komentarza) lub dziennik danego pliku (przy wysyłaniu poprawki pliku CVS prosi o wpisanie informacji dotyczącej danej wersji pliku).
W przypadku deklaracji stałych, prosimy używać jedynie wielkich liter - pozwoli to na wyróżnienie stałych od zmiennych.
W sprawie komend SQL kierujemy się zasadą, że nie należy oszczędzać linijek na to, aby w dłuższych zapytaniach były one czytelniejsze. Czyli: niech zapytania zajmują kilka linijek jeżeli jest to potrzebne - przykład:
$sql = 'SELECT *
FROM ' . TOPIC . '
WHERE topic_id = ' . $_GET['id'];
Słowa kluczowe SQL muszą być napisane wielkimi literami (SELECT, UPDATE, WHERE itp) natomiast nazwy kolumn małymi. Przyjęło się aby całe zapytanie ujmować jedynie w pojedyncze apostrofy. Jak widzisz w powyższym przykładzie w przypadku wstawienia stałej lub zmiennej "rozdzielamy" łańcuch. Jeżeli natomiast chodzi o kolumny typu char() to należy używać apostrofów podwójnych:
$sql = 'UPDATE ' . TOPIC . '
SET topic_subject = "' . $_POST['topic_subject'] . '"';
Oto inne przykłady:
$sql = 'SELECT topic_subject, topic_user, user_name
FROM ' . TOPIC . ', ' . USERS . '
WHERE topic_id = ' . $_GET['id'] . '
AND user_id = topic_id
AND topic_id > 100';
Zwróć uwagę na zapis słów kluczowych AND oraz OR - zostały one zapisane z wcięciem w
wielkości dwóch spacji.