В компьютерном программировании самодокументирующийся (или самоописывающий ) исходный код и пользовательские интерфейсы следуют соглашениям об именовании и соглашениям о структурном программировании , которые позволяют использовать систему без предварительных специальных знаний. [1] В веб - разработке самодокументирование относится к веб-сайту, который раскрывает весь процесс своего создания через общедоступную документацию, и чья общедоступная документация является частью процесса разработки. [ требуется ссылка ]
Обычно заявленные цели для систем самодокументирования включают в себя:
Самодокументирующийся код якобы написан с использованием понятных человеку имен, обычно состоящих из фразы на человеческом языке, которая отражает значение символа, например, article.numberOfWords или TryOpen . Код также должен иметь ясную и чистую структуру, чтобы человек-читатель мог легко понять используемый алгоритм.
Существуют определенные практические соображения, которые влияют на то, могут ли быть реализованы цели системы самодокументирования и насколько хорошо они будут реализованы.
Ниже приведен очень простой пример самодокументируемого кода на языке C , в котором вместо явных комментариев используются соглашения об именовании, что делает логику кода более очевидной для людей, читающих его.
size_t count_alphabetic_chars ( const char * text ) { if ( text == NULL ) return 0 ; size_t количество = 0 ; while ( * текст != '\0' ) { if ( is_alphabetic ( * текст )) count ++ ; текст ++ ; } возврат количества ; } Джеф Раскин раскритиковал веру в «самодокументирующийся» код, заявив, что код не может объяснить логику, по которой пишется программа или почему она реализована именно таким образом. [3]
[…] почти любое числовое значение в исходном коде следует заменить соответствующим символом. Это значительно улучшит самоочевидный аспект исходного кода и значительно облегчит обслуживание кода в долгосрочной перспективе, поскольку позволит искать символы для нахождения связей между различными фрагментами кода. […]