Kod samodokumentujący - Self-documenting code

W programowaniu komputerowym , samodokumentujące (lub własny opisując ) kod źródłowy i użytkowników interfejsy śledzić konwencje nazewnictwa i programowania strukturalnego konwencje, które umożliwiają korzystanie z systemu bez wcześniejszej znajomości konkretnego. W tworzeniu stron internetowych , samodokumentujące odnosi się do strony internetowej, która naraża cały proces jej tworzenia poprzez dokumentacji publicznej i publicznego, którego dokumentacja jest częścią procesu rozwoju.

Cele

Powszechnie określane cele systemów samodokumentujących obejmują:

Konwencje

Self-dokumentowania kodu rzekomo napisany przy użyciu nazw czytelny dla człowieka, zwykle składające się z zwrotem w ludzkim języku, który odzwierciedla znaczenie symbolu'S, takich jak article.numberOfWords lub TryOpen . Kod musi mieć również przejrzystą i przejrzystą strukturę, aby czytelnik mógł łatwo zrozumieć zastosowany algorytm.

Względy praktyczne

Istnieją pewne praktyczne względy, które wpływają na to, czy i jak dobrze można zrealizować cele systemu samodokumentującego.

Przykłady

Poniżej znajduje się bardzo prosty przykład samodokumentującego się kodu, przy użyciu konwencji nazewnictwa zamiast jawnych komentarzy, aby logika kodu była bardziej oczywista dla czytelników. 

size_t count_alphabetic_chars(const char *text)
{
    if (text == NULL)
        return 0;

    size_t  count = 0;

    while (*text != '\0')
    {
        if (is_alphabetic(*text))
            count++;
        text++;
    }

    return count;
}

Krytyka

Jef Raskin krytykuje wiarę w „samodokumentujący się” kod, mówiąc, że kod nie może wyjaśnić powodów, dla których program jest pisany lub dlaczego jest wdrażany w taki sposób.

Zobacz też

Bibliografia

Dalsza lektura