Вопросы с тегом «documentation»

Многие люди утверждают, что «комментарии должны объяснять« почему », а не« как »». Другие говорят, что «код должен быть самодокументированным», а комментарии должны быть скудными. Роберт К. Мартин утверждает, что (перефразируя мои собственные слова) часто «комментарии - это извинения за плохо...

Меня специально попросили давать построчное (или, в зависимости от случая, например, изображение за изображением и т. Д.) Объяснение или комментарий, которые мой начальник хочет прочитать и соблюдать. Поскольку он не программист, он не может следовать коду, поэтому хочет, чтобы все было переведено...

Стандарт RFC 2606 резервирует доменные имена example.org , example.net и example.com с целью использования в качестве примеров в документации. Что является эквивалентом телефонного номера (включая код страны), который можно использовать в качестве примера, например, для предоставления пользователям...

Предположим, что я разрабатываю относительно большой проект. Я уже задокументировал все свои классы и функции с помощью Doxygen, однако у меня была идея поместить «заметки программиста» в каждый файл исходного кода. Идея заключается в том, чтобы объяснить в терминах непрофессионала, как работает...

Во время встречи, посвященной откату стороннего SDK из последней версии, было отмечено, что наши разработчики уже отметили в истории фиксации, что последняя версия не должна использоваться. Некоторые разработчики утверждали, что это плохая практика, и вместо этого ее следует отметить либо в...

Я работаю над довольно большим проектом и получил задание сделать несколько переводов для него. Было множество этикеток, которые не были переведены, и пока я копался в коде, я нашел этот маленький кусочек кода //TODO translations Это заставило меня задуматься над смыслом этих комментариев для себя...

Я написал следующий код: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom());...

Прежде всего, в этом вопросе я бы хотел избежать полемики о том, является ли комментирование исходного кода хорошим или плохим. Я просто пытаюсь понять, что люди имеют в виду, когда говорят о комментариях, которые говорят вам, ПОЧЕМУ, ЧТО или КАК. Мы часто видим рекомендации типа «Комментарии...

Я работал над проектом три месяца назад, а затем внезапно появился другой срочный проект, и меня попросили перевести мое внимание. С завтрашнего дня я вернусь к старому проекту. Я понимаю, что я не помню, что именно я делал. Я не знаю с чего начать. Как я могу задокументировать проект так, чтобы...

Я планирую оставить свою текущую работу, потому что мы заблокированы в использовании Blub , с корпоративной средой Blub и веб-сервером уровня Blub, на посредственном виртуальном хостинге. Мои коллеги дружелюбны, а мой начальник - средний владелец малого бизнеса - я хочу полностью уйти по...

Я понимаю важность хорошо документированного кода. Но я также понимаю важность самодокументируемого кода. Чем проще визуально прочитать определенную функцию, тем быстрее мы можем двигаться во время обслуживания программного обеспечения. С учетом сказанного я люблю разделять большие функции на...

Автоматическое создание документации может быть выполнено с помощью различных инструментов, причем GhostDoc является одним из наиболее заметных. Однако по определению все, что он генерирует, является излишним. Он рассматривает имена методов, классов и т. Д. И выводит английский язык, который может...

Я пишу пользовательскую документацию (СОП), которая включает сторонние программы, которые я пытаюсь описать хорошо. Одной из таких программ является сервер, который мало показывает индикацию своего запуска, кроме графики, которая отображается во время процедуры инициализации / запуска. Как...

Иногда я нахожусь в ситуациях, когда часть кода, которую я пишу, является (или кажется ) настолько очевидной, что ее имя будет в основном повторяться в виде комментария: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; };...

Когда вы используете такие инструменты, как jsdocs , он генерирует статические HTML-файлы и их стили в вашей кодовой базе на основе комментариев в вашем коде. Должны ли эти файлы быть добавлены в репозиторий Git или их следует игнорировать с помощью...

Одной из основных целей компаний-разработчиков программного обеспечения является увеличение их шинного фактора. Об этом также говорится в докладе, организованном Google . Это означает, что вы должны кодировать и документировать все так, чтобы, если завтра вас переедет автобус, проект все еще может...

Кажется, есть отвращение к написанию даже самой базовой документации. Наш проект README относительно голый. В документах нет даже обновленных списков зависимостей. Есть ли что-то, чего я не знаю в индустрии, что заставляет программистов не любить писать документацию? Я могу напечатать абзацы...

Работая над кодом, я сталкиваюсь со многими из тех же проблем, что и мои товарищи по команде, и я написал несколько полезных функций и классов, и они тоже. Если будет хорошее общение, я услышу о какой-то замечательной вещи, которую кто-то собрал, и через шесть месяцев, когда мне это понадобится, я...

Я пишу (надеюсь) полезные комментарии в кодовой (C ++) документации типа: The reason we are doing this is... Причина, по которой я использую «мы» вместо «я», заключается в том, что я много пишу в академической среде, где «мы» часто предпочитают. Итак, вот вопрос. Есть ли веская причина отдавать...

Программа CS моей школы избегает каких-либо упоминаний об объектно-ориентированном программировании, поэтому я немного читал сам, чтобы дополнить его - в частности, конструкцию объектно-ориентированного программного обеспечения Бертрана Мейера. Мейер неоднократно подчеркивал, что классы должны...