Как использовать кодовую документацию для проекта?

Ответ 1

IMO вам нужна документация API и множество примеров.

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

Это основа хорошей практики и SOA, поэтому вы действительно должны отказаться от подхода "самодокументирующего кода".

Алфавитный список функций/методов/свойств/имеет значение после того, как клиент "получил", но до тех пор он не сразу полезен.

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

Как только у вас есть это, поместите его в Wiki и попросите своих пользователей улучшить его. Подумайте, используя что-то интерактивное, как платформа, подобная стеку. MSDN - хорошая модель, но их примеры часто сосут и могут не иметь контекста. У вас может быть роскошь иметь более жесткие и конкретные приложения, чем, скажем, всю платформу .NET. Раннее реагирование на вопросы и обновления ваших примеров/документации обеспечит ваше сообщение в начале жизненных циклов. Это поможет быстро снизить затраты на документацию, заглянув за вашими клиентами и предоставив им полезную, практическую помощь.

Надеюсь, что это поможет.

Ответ 2

Хороший вопрос. Конечно, у меня нет универсального решения. Кодовая документация в стиле msdn/sun - хорошая база. Но для концепций, архитектуры и так вам нужно больше, чем это. В некоторых проектах мы используем вики для этого. Для запросов клиентов у нас есть своего рода билетная система, в которой мы также храним некоторые (без кода) информацию для решения. В общем, нет никакого центрального места для всего документального материала.

Изменить: ваш код сам по себе - лучшая документация, следуя рекомендациям по чистым кодам или что-то еще - это настоящая передовая практика:-)

Ответ 3

Вики - это крекинг-идея (хорошее предложение @Micha!). Раньше я использовал его в предыдущей компании для крупного проекта инженерного программного обеспечения/оборудования. Это, очевидно, было связано с аппаратными и программными ребятами, и это был отличный способ поделиться информацией по всем командам. Это действительно полезно, если это долгосрочный проект - вы можете отслеживать изменения в функциональности /API, поскольку вещи неизбежно меняются со временем.

Мы использовали платный сервис - Confluence, если я правильно помню; но есть бесплатные сайты для вики-сайтов, например. wikihost (просто быстрый поиск по Google, я не могу ручаться за них).

В другой заметке - подумал ли ты о самодокументировании кода? Например, "Doxygen" или подобное? Большую массу усилий испытывает отсутствие документирования каждой отдельной функции, а также создание достойной структуры, которая может быть дополнена дополнительной информацией, когда это необходимо. Он также создает приятный интерфейс для перехода через все функции/класс и т.д.

Изменить: Я фактически начал использовать Сайты Google (sites.google.com), чтобы создать вики для команды разработчиков, с которой я не работаю. Это бесплатно (как в "пиве" ) и кажется довольно хорошим до сих пор, хотя в нем нет автоматического форматирования кода.

Ответ 4

В моих проектах я использую краткое описание в своих файлах классов вверху, например:

//======
//
//  modul:      fileRunner.cs
//  ...
//  what:       for playing audio/video
//  depends on: consoleOutput.cs (Form)
//
//=======
#region HowToUse
//=======
//
//          HowToUse
//
//      1. create instance of fileRunner:
//          fileRunner p = new fileRunner();
//      2. run console program [progPath] with arguments [cmdsString]
//          string output = p.RunExternalExe(progPath, cmdsString);
//      3. handle [output]
//          if (output == "anyError"){do something;}
//
//  [OUTPUT]
//      "0" : process ended w/o errors
//      "C" : canceled by user
//      else: output is the string of the StdError, the called program submitted + StdOut after "Std output:"
//
//  IMPORTANT
//  Mention, this file depends on consoleOutput.cs to parse the output for gui.
//  It doesn't support input ways, because the way ffmpeg is outputting doesn't allow it, it not active
//=======
#endregion

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

#region convert an audio or video file from a drop
// FUNCTION:    convertTo
// DOES:        converting a file from a drop
//              does not delete the original
// INPUT1:      [path] as string, 
//                  path to the destination file
// INPUT2:      [e] as System.Windows.Forms.DragEventArgs,
//                  the args, the drop-object submits
//                  path of source file is in here
// OUTPUT:      isConverted as bool,
//                  true if not (canceled or error raised)
    public bool convertTo(string pWorkingFile, DragEventArgs e)
    {
       ...
    }
#endregion

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

Ответ 5

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

Ваша документация также может быть в вики, а затем вы можете просто отправить Spongebob ссылку.

Ответ 6

Чтобы уменьшить боль, связанную с изменением спецификаций по большому api, я предлагаю вам следовать соглашению msdn/javadoc, как упоминалось ранее, а также посоветовать вашему товарищу по команде использовать современную среду IDE с функцией autocompletion/autosuggest. Большинство распространенных редакторов, которые предоставляют автоматическое предложение, также отображают документацию для используемого метода/члена. Если вы ищете ловкость здесь, то документы и вики имеют небольшой перебор; мои 2 цента.

Ответ 7

Почему бы вам просто не поместить свою работу в один проект git/svn вместо самостоятельной работы над частью проекта? Затем, когда вы меняете основную функцию, вы увидите, что она сломает и нести ответственность за исправление методов, которые вызывают ее, прежде чем совершать изменения.

Я не большой поклонник документирования во время разработки. Это слишком замедляет вас, и вам придется повторять его снова и снова. Просто создайте описательные имена методов и будьте щедры с комментариями в коде.

Ответ 8

Для начала:

Чтобы помочь ситуации между spongebob и вами, работая вместе, вам понадобится программное обеспечение для управления кодом (GIT, TFS и т.д.).

Что делать, если я меняю GetWindow() на GetWindow (название строки). Теперь, как я буквально говорю бедному spongebob, ему нужно переделать его код.

Вы всегда должны начинать свое дневное кодирование с "GET LATEST", то есть загружать код из репозитория. Если spongebob сделает это, он сразу увидит, что ему теперь нужно передать заголовок строки, поскольку его код прекратит компиляцию. Было бы предпочтительнее, чтобы вы в буквальном смысле сказали spongebob, что вы изменили свой код, и теперь ему нужно передать значение, но если вы оба проверяете код каждую ночь и получаете последние, когда начинаете кодирование в течение дня, вы должны быть проинформированы.

Что касается использования WIKI или если вы используете Sharepoint, это не имеет значения. Я бы сказал, чтобы сделать его немного более эффективным, почему бы не сделать это:

В вашем репозитории документов (Wiki/Sharepoint) вызовите файлы по названию страницы, чтобы один из них был WordArt, другой - MainDocument, возможно, это PrintDocument (при условии, что это разные страницы), а в коде вы можете просто поставить:

Для получения дополнительной информации об этом посещении ___site: http://yourrespositoryname.com/nameofprocedure