Wskazówki dla piszących.

ZbeeGin · Post autor: **ZbeeGin** » 10 mar 2007, 14:00

Jako częsty czytelnik tego i pokrewnych działów forum, pragnę wszystkim piszącym w tym dziale przedstawić wskazówki, które wypada uwzględnić podczas zakładania nowych tematów lub pisania odpowiedzi w bieżących tematach dotyczących problemów z autorskimi programami (kody źródłowe); badź z oprogramowaniem służącym do tworzenia, testowania lub analizowania tych kodów.

__________________________________________

1. W temacie należy w formie prefix-u zawrzeć rodzaj użytego oprogramowania lub języka za pomocą którego powstał kod źródłowy programu. Przykłady tematów, w których zastosowano prefix:

[BASCOM] Mam problem z przerwaniami PCI w ATmega16
[AVRGCC] Jak obsłużyć przerwania?
[ASM] LDI nie pozwala użyć rejestru R0...R15

Jeśli temat jest ogólny i nie pozwala przyporządkować problemu do konkretnej kategorii to prefix można pominąć. Można także łączyć prefix-y, aby wskazać, że problem dotyczy połączenia jednego środowiska z drugim:

[BASCOM+ASM] Wstawka pobierająca dane ze zmiennych

2. W treści postu należy podać do jakiej wersji oprogramowania post się odnośi, o ile nie wynika to z samej treści opisującej problem. Ważne jest podanie numeru wersji i jej charakteru (pełna, trial, demo, beta).

Przykład z opisem w tekscie:

Mam problem z pewnym programem. Został on napisany w języku C (AVR-GCC wersja 20070101 Beta). Otórz nie potrafię go skompilować bezpośrednio z AVR Studio (wersja 4.12b). Wyskakuje nieznany błąd i AVR Studio się zamyka. (...)

Przykład z dopiskiem końcowym/początkowym:

Używam programu BASCOM AVR 1.11.8.3 DEMO.

3. Kody źródłowe należy umieszczać w tagach CODE. Programy będą wtedy wyświetlone czcionką o stałej szerokości, wobec czego będą bardziej czytelne, szczególnie gdy użyto wcięć do wskazania logicznych struktur w programach.

Przykład:

Kod: Zaznacz cały

Licznik = 0
Pokaz = 1
Do
  If Pokaz = 1 Then
    Cls
    Print Licznik ; " " , "Osób"
    Pokaz = 0
  End If
Loop

End

Można to łatwo zrobić już po wklejeniu kodu źródłowego. Zaznaczamy tekst i naciskamy przycisk CODE.
Uwaga! Wszelkie dalsze formatowania w bloku CODE nie są możliwe!

W treści postu można również umieścić jedną linię kodu, dla której nieopłacalne jest stosowanie tagów CODE. Jednakże linia taka powinna być oddzielona od treści pustymi liniami.

Przykład:

Nie możesz użyć:

LDI R1, 0x20

tylko:

LDI R16, 0x20

Takie ograniczenia wprowadzili projektanci z firmy Atmel. (...)

4. Jeśli kod źródłowy jest dłuższy niż 30 linijek, należy go umieścić jako załącznik, a problematyczny fragment wkleić w treść zamykając go w tagi CODE jak w punkcie trzecim. Wszyscy wiemy jak długie mogą być kody źródłowe, zwłaszcza w języku asembler.

5. Przy opisywaniu/wskazywaniu usterek w przedstawionych kodach źródłowych należy pokazywać tylko istotne jego fragmenty. Najlepiej pokazując tylko jeden blok strukturalny lub zmienioną linię wraz z najbliższym otoczeniem tej linii, by można było ją łatwo zidentyfikować.

Przykład:

Patrz tutaj:
Kod: Zaznacz cały
    Cls
    Print Licznik ; " " , "Osób"
Zamiast średnika dałeś przecinek! To on powoduje, że słowo Osób jest odsunięte od liczby.

6. Komentarze w programach są narzędziem pozwalającym przywrócić nie tylko ulotną pamięć osoby piszącej program. Dla Nas komentarze pozwolą łatwiej zrozumieć jak działa program i jakie były założenia co do jego treści (Co nie musi być zbieżne!). Zatem uprasza się by kody źródłowe były wyposażone w komentarze autorskie.
_______________________________________________

Mam nadzieję, że podane wskazówki przyśpieszą rozwiązywanie poruszonych problemów. A wszystkim użytkownikom ułatwią czytanie i analizowanie tychże problemów.

Moderator, ZbeeGin