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

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

236 programming-practices  documentation  comments 

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

155 documentation 

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

112 documentation  standards  help-documentation 

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

104 documentation  large-scale-project 

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

94 version-control  documentation 

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

86 documentation  comments 

Я написал следующий код: 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()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Здесь есть закомментированная строка. Но я думаю, что это делает код более понятным, делая очевидной …

83 documentation  comments 

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

78 documentation  comments 

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

72 project-management  documentation 

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

66 career-development  documentation 

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

63 programming-practices  code-quality  documentation 

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

60 documentation  automation  automatic-programming 

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

59 documentation  component  jargon 

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

54 programming-practices  documentation  language-agnostic 

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

49 git  documentation