Каков наилучший способ доказать, что внутрикодовая документация больше, чем обширная внешняя документация?

Каков наилучший способ доказать моему боссу, что в документации по коду больше, чем обширные внешние документы, содержащие документацию и скриншоты кода /ui?

У нас есть группа в компании, которая управляет кодом SAP. Их процесс документирования включает в себя часы трудоемкой документации и скриншоты кода и интерфейса (до и после).

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

Есть ли опубликованные исследования крупных компаний, которые говорят, что внешняя документация устарела и что в комментариях кода более эффективны? (или что-то подобное этой точке)

Это не имеет никакого отношения к пользователям. Это НЕ учебная документация пользователя. Только внутреннее использование.

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

Вы действительно хотите, чтобы скриншот ваш код до и после каждого изменения одного ребенка, а затем написать документ, объясняющий изменение на большой глубине? когда никто не будет использовать эти документы в качестве справочного материала в будущем?

6 голосов | спросил jordan.peoples 22 PMpMon, 22 Apr 2013 20:48:32 +040048Monday 2013, 20:48:32

4 ответа


5

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

«внешняя» документация имеет столь же важное значение, как и код, вы должны иметь возможность сообщать, что делает код, как он это делает (в широком смысле) и почему он это делает. Эти вещи не могут быть встроены в мелкозернистую кодовую базу. Конечно, вы также можете делать внутренние документы кода, и они могут быть автоматически сгенерированы, но я всегда считал их немного бессмысленными по сравнению с просто чтением кода (и встроенных комментариев).

Если вы правы, то документация не должна быть трудоемкой задачей, написанной в огромных документах Word. Вы можете сделать задачу намного проще, написав ее на легком языке разметки (например, ASCIIDoc или ReStructured Text), который затем может быть скомпилирован в форматы Word или HTML. Эта документация «источник» затем может быть отредактирована в вашей среде IDE, так как это только текстовые файлы, и вы также можете применять инструменты проверки кода и свой SCM. Этот подход значительно упрощает задачу документирования для разработчиков.

ответил gbjbaanb 22 PMpMon, 22 Apr 2013 22:28:35 +040028Monday 2013, 22:28:35
1

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

Ваши сверстники SAP могут переусердствовать для потребления разработчиком, но я бы предположил, что их документация хорошо перетекает в страницы справки или в Руководство пользователя. Комментарии кодов не помогают продавать приложение руководству на ранних стадиях. Требования и высокоуровневые проектные документы не очень хорошо вписываются в код, но, безусловно, имеют решающее значение для понимания каждым человеком правильного /ожидаемого поведения.

ответил cdkMoose 22 PMpMon, 22 Apr 2013 21:00:41 +040000Monday 2013, 21:00:41
1

Вы можете создавать файлы справки из комментариев XML в исходном коде. SandCastle может принимать эти комментарии и создавать хорошие файлы справки, которые вы можете дополнить концептуальной документацией.

EDIT: инструменты позволяют:

  1. Приводит ваши комментарии к коду во внешнюю документацию
  2. Источником ваших документов является версия без лишних усилий (поскольку ваш исходный код уже есть, правда?)
  3. Если вам нужно объяснить концепции более новым разработчикам, приложение менеджера проектов docs имеет (полупристойный) редактор для так называемых «концептуальных документов» на XML-языке. Я использовал себя, редактор достаточно хорош, чтобы это не было проблемой.
  4. Я не помню детали из памяти, но я считаю, что вы можете связать все это (на основе кода и концептуального) контента друг с другом, что позволит вам получить что-то в строках помощи VS.

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

ИЗМЕНИТЬ 2: Отвечая на второе редактирование OP, то, что он ищет, является своего рода списком изменений, чтобы ответить, почему (и когда) произошли некоторые изменения.

Вы можете реализовать его по коду или внешнему артефакту «концептуального контента», который вы меняете (или генерируете) из своих крючков системы управления исходным кодом. Таким образом, каждый раз, когда вы создаете документацию, он получает документ «Что нового в этой версии» в легкодоступном формате.

Это может быть даже другой файл проекта документации из основного проекта документа (это означает, что он может быть сгенерирован отдельно и с разными настройками презентации).

Кстати, кажется, ваш босс ищет какую-то модель. Процесс SAP выглядит слишком много, но вы можете показать ему то, что он пытается достичь (что является прослеживаемостью изменений: вопрос «кто, когда и что») автоматизированным (и презентабельным) способом.

PS: Система отслеживания ошибок также поможет здесь, так как вы можете включить запрос изменения (или файл ошибки #), который также послужил поводом для изменения.

ответил Fabricio Araujo 22 PMpMon, 22 Apr 2013 22:15:20 +040015Monday 2013, 22:15:20
0
  

Каков наилучший способ доказать моему боссу, что в документации по коду больше, чем обширные внешние документы, содержащие документацию и скриншоты кода /ui?

Это может быть, но это не правило. Для чего будет использоваться документация? (Кто обращается к нему? Как часто? Какие отзывы /решения выходят из этой деятельности?)

  

Процесс их документации включает в себя часы трудоемкой документации и скриншоты кода и интерфейса (до и после).

     

Вы действительно хотите сделать скриншот своего кода до и после каждого изменения одного ребенка, а затем написать документ, объясняющий изменение на большой глубине?

Кажется, что они делают это неправильно '* - им не нужна ваша документация - им нужна записка где-то, говоря:

git/hg/svn/xyz diff -rXXXX -rYYYY # show code differences
git/hg/svn/xyz info XXXX          # show change description and details

или что-то подобное. Это легко может быть автоматизировано с помощью любого хорошего SCM или с любыми вашими результатами («выпуски функций», «запросы на изменение», «отчеты о завершении итерации», «публичные коммиты», «разрешенные дефекты» и т. Д.).

  

, когда никто никогда не будет использовать эти документы в качестве справочного материала в будущем?

Если их никто никогда не будет использовать, то легко доказать: никто их никогда не будет использовать. Можете ли вы поговорить с ними, чтобы узнать, действительно ли это так?


'* - Я не уверен, действительно ли они делают это неправильно. Это зависит от того, для чего используется эта документация.

ответил utnapistim 24 PMpWed, 24 Apr 2013 22:10:06 +040010Wednesday 2013, 22:10:06

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132