 | Эта статья требует дополнительных ссылок для проверки . ( март 2020 г. ) ( Узнайте, как и когда удалить это сообщение-шаблон ) |
В компьютерном программировании , самодокументированно (или самоописываемые ) исходный код и пользовательские интерфейсы следуют именованиям и структурное программирование конвенции , которые позволяют использовать систему без предварительных конкретных знаний. [1] В веб - разработки , самодокументирован относится к веб - сайт , который предоставляет весь процесс ее создания с помощью публичной документации, и чья публичная документация является частью процесса разработки. [ необходима цитата ]
Цели [ править ]
Обычно заявляемые цели для самодокументирующих систем включают:
- Сделайте исходный код более легким для чтения и понимания [2]
- Сведите к минимуму усилия, необходимые для поддержки или расширения унаследованных систем [2]
- Снижение потребности пользователей и разработчиков системы в обращении к вторичным источникам документации, таким как комментарии к коду или руководства по программному обеспечению [2]
- Упростите автоматизацию за счет автономного представления знаний
Соглашения [ править ]
Самодокументирован код якобы написан с использованием имен удобочитаемых, как правило , состоящий из фразы на языке человека , который отражает смысл этого символа, например, article.numberOfWords или TryOpen . Код также должен иметь четкую и чистую структуру, чтобы читатель мог легко понять используемый алгоритм.
Практические соображения [ править ]
Существуют определенные практические соображения, которые влияют на то, насколько хорошо могут быть реализованы цели для системы самодокументирования.
- единообразие соглашений об именах [2]
- последовательность [2]
- область применения и системные требования
Примеры [ править ]
Ниже приведен очень простой пример самодокументирующегося кода, в котором вместо явных комментариев используются соглашения об именах, чтобы сделать логику кода более очевидной для читателей.
size_t count_alphabetic_chars ( const char * text ) { if ( text == NULL ) return 0 ; size_t count = 0 ; while ( * текст ! = '\ 0' ) { if ( is_alphabetic ( * text )) count ++ ; текст ++ ; } счетчик возврата ; }Критика [ править ]
Джеф Раскин критикует веру в «самодокументирующийся» код, говоря, что код не может объяснить причины, по которым программа пишется или почему она реализована таким образом. [3]
См. Также [ править ]
- Автологическое слово
- Читаемость кода
- Комментарий (компьютерное программирование)
- Контролируемый естественный язык
- Грамотное программирование
- Программирование на естественном языке
Ссылки [ править ]
- ^ Schach, Стивен Р. (2011). Объектно-ориентированная и классическая программная инженерия (8-е изд.). McGraw-Hill Professional . С. 505 –507. ISBN 978-0-07337618-9. OCLC 477254661 .
- ^ a b c d e Пол, Матиас Р. (9 апреля 2002 г.). «Re: [fd-dev] ОБЪЯВЛЕНИЕ: CuteMouse 2.0 alpha 1» . freedos-dev . Архивировано 24 марта 2020 года . Проверено 24 марта 2020 .
[…] Почти любое числовое значение в исходном коде должно быть заменено соответствующим символом.
Это значительно улучшило бы очевидный аспект исходного кода и значительно упростило бы обслуживание кода в долгосрочной перспективе, так как позволило бы искать символы для нахождения связей между различными фрагментами кода.
[…]
- ↑ Раскин, Джеф (18 марта 2005 г. ). «Комментарии важнее кода - тщательное использование внутренней документации - один из самых недооцененных способов улучшения качества программного обеспечения и ускорения внедрения» . Очередь ACM . Разработка. ACM, Inc. 3 (2). Архивировано 24 марта 2020 года . Проверено 22 декабря 2019 . [1] [2]
Дальнейшее чтение [ править ]
- МакКоннелл, Стив . «Контрольный список процедур высокого качества» . Код завершен .
