Wskazówki dla piszących.

[ZbeeGin]

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 przerwaniem INT0 w 89c2051
[C] Jak obsłużyć przerwania?
[ASM] Jak używać rozkazu DA A?

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 (KEIL C51 8.08, wersja ewaluacyjna). Otórz nie potrafię go skompilować gdyż wyskakuje błąd braku bliblioteki "sw_USB" (...)

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

Używam programu BASCOM 8051 2.11 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:

Tu masz błąd. Zamiast:

MOV R1, 0x20

musisz użyć:

MOV R1, #20h

Chodzi przecież o załadowanie stałej, nie o załadowanie wartości spod adresu 20H. (...)

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