Samodokumentující kód - Self-documenting code

v programování, samodokumentování (nebo popisující sebe) zdrojový kód a uživatelská rozhraní následovat konvence pojmenování a strukturované programování konvence, které umožňují použití systému bez předchozích konkrétních znalostí.^[1] v vývoj webových aplikací, samodokumentování označuje web, který prostřednictvím veřejné dokumentace odhaluje celý proces jeho vytváření a jehož veřejná dokumentace je součástí procesu vývoje.^{[Citace je zapotřebí ]}

Cíle

Běžně stanovené cíle pro samodokumentační systémy zahrnují:

Usnadněte čtení a pochopení zdrojového kódu^[2]
Minimalizujte úsilí potřebné k údržbě nebo rozšíření starších systémů^[2]
Snižte potřebu, aby uživatelé a vývojáři systému museli konzultovat zdroje sekundární dokumentace, jako je komentáře k kódu nebo softwarové příručky^[2]
Usnadnit automatizace prostřednictvím soběstačnosti reprezentace znalostí

Konvence

Samodokumentující kód je zdánlivě psán s použitím lidských čitelných jmen, obvykle sestávajících z fráze v lidském jazyce, která odráží význam symbolu, jako například article.numberOfWords nebo TryOpen. Kód musí mít také jasnou a čistou strukturu, aby lidský čtenář mohl snadno porozumět použitému algoritmu.

Praktické úvahy

Existují určité praktické úvahy, které ovlivňují, zda a jak dobře lze realizovat cíle pro samodokumentující systém.

uniformita konvence pojmenování^[2]
konzistence^[2]
rozsah aplikace a Požadavky na systém

Příklady

Níže je uveden velmi jednoduchý příklad samodokumentujícího kódu, který pomocí konvencí pojmenování namísto explicitních komentářů zvýší jasnost logiky kódu pro lidské čtenáře.

size_t count_alphabetic_chars(konst char *text){    -li (text == NULA)        vrátit se 0;    size_t  počet = 0;    zatímco (*text != '\0')    {        -li (is_alphabetetic(*text))            počet++;        text++;    }    vrátit se počet;}

Kritika

Jef Raskin kritizuje víru v „samodokumentující“ kód tím, že říká, že kód nedokáže vysvětlit důvody, proč je program psán, nebo proč je implementován takovým způsobem.^[3]

Viz také

Reference

^ Schach, Stephen R. (2011). Objektově orientované a klasické softwarové inženýrství (8 ed.). McGraw-Hill Professional. str.505 –507. ISBN 978-0-07337618-9. OCLC 477254661.
^ ^A ^b ^C ^d ^E Paul, Matthias R. (04.04.2002). „Re: [fd-dev] OZNAM: CuteMouse 2.0 alpha 1“. freedos-dev. Archivováno od původního dne 2020-03-24. Citováno 2020-03-24. […] Téměř jakákoli číselná hodnota ve zdrojovém kódu by měla být nahrazena odpovídajícím symbolem. To by výrazně zlepšilo samozřejmý aspekt zdrojového kódu a významně by z dlouhodobého hlediska usnadnilo údržbu kódu, protože by to umožnilo vyhledávat symboly a hledat vztahy mezi různými výňatky kódu. […]
^ Raskin, Jef (2005-03-18). „Komentáře jsou důležitější než kód - důkladné používání interní dokumentace je jedním z nejvíce přehlížených způsobů, jak zlepšit kvalitu softwaru a urychlit implementaci.“. Fronta ACM. Rozvoj. ACM, Inc. 3 (2). Archivováno od původního dne 2020-03-24. Citováno 2019-12-22. [1][2]

Další čtení

McConnell, Steve. „Kontrolní seznam vysoce kvalitních rutin“. Kód dokončen.

Tento programovací jazyk související článek je a pahýl. Wikipedii můžete pomoci pomocí rozšiřovat to.

[Schach_2011-1] Schach, Stephen R. (2011). Objektově orientované a klasické softwarové inženýrství (8 ed.). McGraw-Hill Professional. str.505 –507. ISBN 978-0-07337618-9. OCLC 477254661.

[Paul_2002_Symbols-2] A ^b ^C ^d ^E Paul, Matthias R. (04.04.2002). „Re: [fd-dev] OZNAM: CuteMouse 2.0 alpha 1“. freedos-dev. Archivováno od původního dne 2020-03-24. Citováno 2020-03-24. […] Téměř jakákoli číselná hodnota ve zdrojovém kódu by měla být nahrazena odpovídajícím symbolem. To by výrazně zlepšilo samozřejmý aspekt zdrojového kódu a významně by z dlouhodobého hlediska usnadnilo údržbu kódu, protože by to umožnilo vyhledávat symboly a hledat vztahy mezi různými výňatky kódu. […]

[Raskin_2005-3] Raskin, Jef (2005-03-18). „Komentáře jsou důležitější než kód - důkladné používání interní dokumentace je jedním z nejvíce přehlížených způsobů, jak zlepšit kvalitu softwaru a urychlit implementaci.“. Fronta ACM. Rozvoj. ACM, Inc. 3 (2). Archivováno od původního dne 2020-03-24. Citováno 2019-12-22. [1][2]

[1]

[2]

[3]