Pary_anime
Komentarze
Zazwyczaj, po przygotowaniu skryptu, gdy patrzymy na piêknie napisany kod widz±c jego przejrzysto¶æ jeste¶my zafascynowani, ¿e nawet nie potrzeba s³owa komentarza. Wszystko jest oczywiste. Ale ju¿ tydzieñ pó¼niej tak oczywistym to nie jest, a po miesi±cu... Po trzech to ju¿ czara magia.
No có¿ ka¿dy przez to przeszed³.
Komentarze powinny opisaæ jak wszystko dzia³a. W zasadzie nigdy komentarzy zbyt wiele, ale jak pominiesz to, ¿e "obieca³e¶ zrobiæ co¶ z tym plikiem tydzieñ temu, ale, ¿e zabalowa³e¶, to dopiero zabra³e¶ za niego trzy dni pó¼niej a tak naprawdê to robisz dopiero dzisiaj i strasznie boli Ciê g³owa, etc... to chyba siê nikt nie pogniewa.
Nag³ówek
Ka¿dy plik powinien zawieraæ informacje wed³ug poni¿szego wzoru, gdzie cze¶æ:
- * pierwsza - informacje co do u¿ywanego edytora i jego ustawieñ,
- * wersja oprogramowania, dla której pisany by³ kod
- * trzecia nazwê pliku,
- * czwarta - od projektu podstawowego,
- * pi±ta - opis zadañ wykonywanych przez plik (bez przesady oczywi¶cie i nawet mo¿e byæ pominiêta, je¶li nazwa pliku wskazuje na zadania wykonywane przez plik),
- * szósta - opis zmiennych (z wyszczególnieniem tych, które korzystaj± z warto¶ci domy¶lnych),
- * siódma - niezbêdnych plików do funkcjonowania,
- * ósma - zasad korzystania, kopiowania, u¿ywania i praw autorskich,
- * dziewi±ta - osób, które pracowa³y nad plikiem.
Poni¿ej przedstawiam przyk³ad takiego nag³ówka:
codeDivStart() /* nazwa edytora:
+-------------------------------------------------------------------+
| PHP version 4 |
+-------------------------------------------------------------------+
| index.php |
+-------------------------------------------------------------------+
| Niniejszy plik jest czê¶ci± projektu System Obs³ugi Stron WWW |
+-------------------------------------------------------------------+
| 1. Czynno¶æ pierwsza jaka robi niniejszy plik |
| 2. Czynno¶æ druga |
| 3. Czynno¶æ trzecia |
| 4. Czynno¶æ czwarta |
| 5. Czynno¶æ pi±ta |
+-------------------------------------------------------------------+
| Zmienne: |
| $zmienna1 - ot taki przyk³ad |
| $zmienna2 - ot taki przyk³ad |
| $zmienna3 - ot taki przyk³ad |
+-------------------------------------------------------------------+
| haselka.php - bardzo wazny plik |
+-------------------------------------------------------------------+
| OPROGROMAWANIE MO¯NA STOSOWAC POD WARUNKIEM, |
| ZE UWAZA SIÊ I Z TY ZGADZA DO TEGO CO NASTEPUJE: |
| Autorzy nie ponosza odpowiedzialnosci za dzialanie programu. Cala |
| odpowiedzialnosc spoczywa na osobach konfigurujacych aplikacje |
| lub w inny sposob korzystajacy z kodu |
| Prawa autorskie: Grupa programistów pracuj±cych spo³ecznie i bez |
| jakichkolwiek pieniedzy w ramach projektow OPEN SOURCE. |
| Pozostawiane jest prawo do swobodnego kopiowania, zmieniania kodu |
| jego upowszechniania na zasadach licencji GNU GPL. |
| |
| UWAGA: |
| W przypadku wykorzystania niniejszego oprogramowania lub |
| jego czesci nale¿y umiescic niniejsza uwage, ze nikt nie ma prawa |
| do wlaczania niniejszego kodu w calosci lub tylko jego czesci |
| do aplikacji, za które bêdzie pobieral jakiekolwiek wynagrodzenie |
| Kod ten powinna byæ zawsze dostepna dla wszystkich bezplatnie |
| Z tego ograniczenia sa zwolnieni wszyscy, którzy sa wskazani jako |
| autorzy w projekcie wskazanym w naglowku. |
+-------------------------------------------------------------------+
| Autorzy: |
| rooddee <roodee.serwer.com> |
| ktos_inny < ktos_inny.polbox.com> |
+-------------------------------------------------------------------+
*/
Za autorów uwa¿a siê inicjatorów powstania kodu wraz z osobami, które dokona³y przynajmniej od 10% do 20% zmian w kodzie. Prosta reorganizacja kodu i poprawienie b³êdów nie mo¿e byæ uwa¿ana za wystarczaj±c± podstawê do dodania do listy autorów.
Komentarze w kodzie PHP:
codeDivStart() /* Jedna linia komentarza (zajmuje ca³± liniê) */
codeDivStart() Kod(); // Komentarz w tej samej linii, w której znajduje siê linia.
codeDivStart() /*
* Bardzo wa¿na jedna linia komentarza
*/
codeDivStart() /*
* Wielowierszowy komentarz. Tutaj ju¿ mog± znale¼æ ca³e
* zdania. Wygl±dem swym przypominaj± paragraf
*/
U¿ywany w perlu i shelu sposób komentowania przy pomocy # jest nie poprawny! !
S³owa specjalne w komentarzach
W komentarzach stosuje siê równie¿ s³owa specjalne. Mog± one byæ pomocne w czasie parsowania skryptu.
:TODO: topic
Oznacza, to co jest do zrobienia, po to by o tym nie zapomnieæ
:BUG: [ID_bledu] topic
tak wpisujesz zauwa¿one b³êdy, wyja¶ñ tu co siê dzieje i prawdopodobne przyczyny b³êdu oraz ewentualnie nadaj ID b³êdowi
:KLUDGE:
Je¶li nie jeste¶ zadowolony z wykonanej pracy, to poinformuj o tym i napisz co by¶ zmieni³, gdyby¶ mia³ wiêcej czasu. Ale bez fa³szywej skromno¶ci
:TRICKY:
Poinformuj, ze ta czesc kodu mo¿e kryæ niespodzianku, tak, by je¶li kto¶ chce zmieniaæ kod, to najpierw d³ugo o tym mysla³.
:WARNING:
Ostrze¿ przed czym¶
:PARSE:
czasami nie da siê nic zrobiæ z kodem i trzeba obej¶æ problem. Powiadom o tym.
:ATTRIBUTE: value
Mo¿esz tworzyæ w³asne atrybuty o nazwach stworzonych przez siebie.
W przypadku stosowania s³ów kluczowych w komentarzach wskazane jest by slowo kluczowe by³o pierwszym slowem komentarza, a nastepnie nazwa zapisujacego komentarz i date wpisu w formacie YYMMDD oraz nazwa problemu. Ponizej nale¿y opisaæ problem.
Np.
codeDivStart() /*
* TODO: Sl@o 020907 dokonczyæ ten standard kodowania
* Musze czym szybciej dokoñczyæ ten system kodowania i umie¶ciæ
* go na forum, by inni go skomentowali i nanie¶li
* w³asne poprawki. Mam nadzieje, ze nie skrzycz±.
*/
Komentarze w wersji podstawowej pisane sa w jezyku polskim. Dla celow szerszego upublicznienia aplikacji wykonywane beda wersje w jezyku o charakterze miedzynarodowym.
wszystko ladnie pieknie tylko jedna sprawa
open source to slowa angielskie, mamy nadzieje ze systemu beda uzywac za granica, wiec robimy kompentarze i naglowki po angielsku!
tak samo nazwy zmiennych i funkcji....
Mysle, ze to zalozenie powinno znalezc sie w temacie Styl pracy nad projektem. Gdzie dokonalem niniejszym tej poprawki.
Boje sie jednak, ze ograniczy to liczbe wspolpracownikow na samym poczatku, bo wielu rozumie co czyta, ale niewielu umie poprawnie to napisac...
Moze jakies rozwiazanie posrednie?
Sl@o napisa³(a):
Boje sie jednak, ze ograniczy to liczbe wspolpracownikow na samym poczatku, bo wielu rozumie co czyta, ale niewielu umie poprawnie to napisac...
Moze jakies rozwiazanie posrednie?
kazdy na pewno na tyle zna angielski, ze poradzi sobie z nazwami zmiennych i f-cji. natomiast komentarze mozna przetlumaczyc po zakonczeniu pracy nad danym plikiem (warunek - muszi byc dobrze opisany po polsku)
roodee napisa³(a):
kazdy na pewno na tyle zna angielski, ze poradzi sobie z nazwami zmiennych i f-cji. natomiast komentarze mozna przetlumaczyc po zakonczeniu pracy nad danym plikiem (warunek - muszi byc dobrze opisany po polsku)
Podoba mi sie to rozwiazanie
Ja równie¿ zgadzam siê z pomys³em roodee, ¿e takie komentarze tworzone "on hot" (hiehie, angielski ) mog± byæ pisane po polsku - nie zawsze jest siê w stanie wyraziæ po angielsku w 100% dok³adnie to o co chodzi. W trakcie dalszej pracy nad tym plikiem komentarz mo¿na wywaliæ, a je¶li bêdzie opisywa³ co¶ wa¿nego, przet³umaczyæ na angielski.
!" border="0" /> G³osowanie rozpoczête !
Po d³ugotrwa³ych dyskusjach, przekonywaniu sie (co tu ukrywac) za¿artych k³ótniach postanowili¶my poddaæ projekt standardu pod g³osowanie. Uznali¶my, ¿e lepsze jest wrogiem dobrego, a nasze akademickie dyskusje mog± siê ci±gn±æ w nieskoñczono¶æ. Zawsze mo¿na niedoci±gniêcia poprawiæ pó¼niej.
Bardzo proszê zwolenników PHP i Open Source do wziêcia udzia³u w niniejszym g³osowaniu. Koniec g³osowania planowany na 20 grudnia 2002, a wiêc jeszcze przed
Bo¿ym Narodzeniem.
Myslê, ¿e to przyczyni siê do ruszenia dalszych projektów.
Zg³oszone od dzi¶ na niniejszym forumpropozycje zmian bêd± mog³y byæ g³osowane w po¼niejszym czasie.
Juz wyjasniam dlaczego nie zgadzam sie:
Moim zdaniem naglowek jest zdecydowanie za dlugi. Wyjasnia wiele, ale co w przypadkach, gdy dlugosc kodu bedzie krotsza niz dlugosc naglowka?
syriusz
