R Language
Meta: wytyczne dotyczące dokumentacji

Uwagi

Dawanie dobrych przykładów

Większość wskazówek dotyczących tworzenia dobrych przykładów pytań i odpowiedzi znajduje się w dokumentacji.

• Zrób to minimalnie i przejdź do sedna. Komplikacje i dygresje przynoszą efekt przeciwny do zamierzonego.

• Dołącz zarówno działający kod, jak i wyjaśniającą go prozę. Żadne z nich nie jest wystarczające samo w sobie.

• Nie polegaj na zewnętrznych źródłach danych. Wygeneruj dane lub użyj biblioteki zbiorów danych, jeśli to możliwe:

  library(help = "datasets")
  

Istnieją pewne dodatkowe uwagi w kontekście Dokumentów:

• W razie ?data.frame zajrzyj do wbudowanych dokumentów, takich jak ?data.frame . Dokumenty SO nie są próbą zastąpienia wbudowanych dokumentów. Ważne jest, aby upewnić się, że nowi użytkownicy R wiedzą, że istnieją wbudowane dokumenty, a także, jak je znaleźć.

• Przenieś treść dotyczącą wielu przykładów do sekcji Uwagi.

Styl

Monity

Jeśli chcesz, aby kod można było wkleić, skopiuj monity takie jak R> , > lub + na początku każdej nowej linii. Niektórzy autorzy Dokumentów wolą nie ułatwiać kopiowania i jest to w porządku.

Wyjście konsoli

Dane wyjściowe konsoli powinny być wyraźnie odróżnione od kodu. Typowe podejścia obejmują:

• Dołącz monity o dane wejściowe (widoczne podczas korzystania z konsoli).
• Skomentuj wszystkie dane wyjściowe, zaczynając od # lub ## od każdego wiersza.
• Drukuj w obecnej postaci, ufając wiodącemu [1] aby wyróżniała się na tle danych wejściowych.
• Dodaj pustą linię między kodem a wyjściem konsoli.

Zadanie

= i <- są odpowiednie do przypisywania obiektów R. Użyj odpowiednio spacji, aby uniknąć pisania trudnego do przeanalizowania kodu, takiego jak x<-1 (niejednoznaczne między x <- 1 a x < -1 )

Komentarze do kodu

Wyjaśnij cel i funkcję samego kodu. Nie ma żadnej konkretnej zasady, czy to wyjaśnienie powinno być w prozie czy w komentarzach do kodu. Proza może być bardziej czytelna i pozwala na dłuższe wyjaśnienia, ale komentarze do kodu ułatwiają kopiowanie i wklejanie. Pamiętaj o obu opcjach.

Sekcje

Wiele przykładów jest wystarczająco krótkich, aby nie potrzebować sekcji, ale jeśli ich użyjesz, zacznij od H1 .