Самодокументируемый код

В компьютерном программировании самодокументируемый ( или самоописывающийся ) исходный код и пользовательские интерфейсы следуют соглашениям об именах и соглашениям структурированного программирования , которые позволяют использовать систему без предварительных специальных знаний. ^[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 (*text != '\0')
    {
        if (is_alphabetic(*text))
            count++;
        text++;
    }

    return count;
}

Критика

Джеф Раскин раскритиковал веру в «самодокументируемый» код, заявив, что код не может объяснить причину, по которой программа пишется или почему она реализована таким образом. ^[3]

См. также

Ссылки

^ Шах, Стивен Р. (2011). Объектно-ориентированная и классическая программная инженерия (8-е изд.). МакГроу-Хилл Профессионал . стр. 505–507 . ISBN 978-0-07337618-9 . OCLC 477254661 .
^ Перейти обратно: ^а ^б ^с ^д ^и Пол, Матиас Р. (9 апреля 2002 г.). «Re: [fd-dev] АНОНС: CuteMouse 2.0 альфа 1» . freedos-dev . Архивировано из оригинала 24 марта 2020 г. Проверено 24 марта 2020 г. […] практически любое числовое значение в исходном коде должно быть заменено соответствующим символом. Это значительно улучшило бы интуитивно понятный аспект исходного кода и значительно облегчило бы обслуживание кода в долгосрочной перспективе, поскольку позволило бы искать символы для поиска связей между различными фрагментами кода. […]
^ Раскин, Джефф (18 марта 2005 г.). «Комментарии важнее кода. Тщательное использование внутренней документации — один из наиболее игнорируемых способов повышения качества программного обеспечения и ускорения внедрения» . Очередь АКМ . Разработка. 3 (2). ACM, Inc. Архивировано из оригинала 24 марта 2020 г. Проверено 22 декабря 2019 г. [1] [2]

Дальнейшее чтение

МакКоннелл, Стив . «Контрольный список процедур высокого качества» . Код завершен .

Эта языкам программирования, статья, посвященная незавершена . Вы можете помочь Википедии, расширив ее .

[Schach_2011-1] Шах, Стивен Р. (2011). Объектно-ориентированная и классическая программная инженерия (8-е изд.). МакГроу-Хилл Профессионал . стр. 505–507 . ISBN 978-0-07337618-9 . OCLC 477254661 .

[Paul_2002_Symbols-2] Перейти обратно: ^а ^б ^с ^д ^и Пол, Матиас Р. (9 апреля 2002 г.). «Re: [fd-dev] АНОНС: CuteMouse 2.0 альфа 1» . freedos-dev . Архивировано из оригинала 24 марта 2020 г. Проверено 24 марта 2020 г. […] практически любое числовое значение в исходном коде должно быть заменено соответствующим символом. Это значительно улучшило бы интуитивно понятный аспект исходного кода и значительно облегчило бы обслуживание кода в долгосрочной перспективе, поскольку позволило бы искать символы для поиска связей между различными фрагментами кода. […]

[Raskin_2005-3] Раскин, Джефф (18 марта 2005 г.). «Комментарии важнее кода. Тщательное использование внутренней документации — один из наиболее игнорируемых способов повышения качества программного обеспечения и ускорения внедрения» . Очередь АКМ . Разработка. 3 (2). ACM, Inc. Архивировано из оригинала 24 марта 2020 г. Проверено 22 декабря 2019 г. [1] [2]

[1]

[2]

[3]