Доставка моей библиотеки первого класса. Любые ошибки, которые мне нужно знать?


12

Я веб-разработчик, собирающийся открыть достижение «First Class Library Опубликовал» в своей карьере, и я потею пулями (я всю ночь нервничал, нервничая). Я хотел бы использовать опыт сообщества, чтобы увидеть, есть ли у кого-нибудь какие-либо предложения или рекомендации, чтобы убедиться, что все идет как можно более гладко. Есть ли какие-то особенности или ошибки, о которых мне нужно знать? Что-нибудь особенное в процессе сборки, которое может вернуться, чтобы укусить меня?

Вот где я нахожусь:

  • Библиотека прошла модульное тестирование и имеет покрытие кода примерно 97%
  • API хорошо документирован и созданы XML-документы для поддержки intellisense
  • Я гарантировал, что методы доступа к общедоступным / частным классам являются точными и правильными. То же самое касается всех получателей / установщиков
  • Обработка ошибок не так грациозна, как мне бы хотелось, но я столкнулся с крайним сроком и согласился с тем, что на данный момент это "так хорошо, как должно быть"
  • Нет дружественной регистрации. Debug.Writeline широко использовался ... Недавно я узнал, что это отражение моей неопытности :(

Ваш совет очень ценится!

Библиотека будет использоваться для создания отчетов. Стандартная шляпа - подключается к базе данных только для чтения, выполняет вычисления, форматирует и выводит данные в поток ответов.


Меня привлекли в качестве дополнительного ресурса для одного из ушедших программистов, и это задание было дано мне как проект «порежь зубы». Библиотека классов будет выпущена для использования другими программистами в компании, пока они пишут производственный код.


2
Нужны подробности, релиз как? Выпуск на продажу? Выпуск с открытым исходным кодом для обмена? Выпускать клиенту по контракту вы? Выпуск для остальной части вашей организации по развитию в рамках проекта для вашего работодателя на полный рабочий день? Выпуск версии v1.0 нового продукта для клиента для вашего работодателя, работающего полный рабочий день?
Джимми Хоффа

@JimmyHoffa: добавлены ответы на ваши вопросы. Спасибо, что нашли время!
Мистер JavaScript

1
Представьте, что вы пользователь библиотеки, не зная, как она работает. Используйте это, чтобы построить что-то. Изменить / удалить / добавить вещи на основе опыта. Тогда выпустите это реальным пользователям и получите их обратную связь.
mike30

Может быть, использовать Sandcastle или другую библиотеку, генерирующую документы, чтобы иметь автономный (ish) справочный материал?
Джесси С. Slicer

7
Расслабьтесь. По моему опыту, наличие даже одного единичного модульного теста и одной единственной строки документации API поднимает этот выпуск выше ~ 95% кода, «выпущенного для использования другими программистами в компании».
Carson63000

Ответы:


8

Блокировка в API

Искусство эффективного построения API - это не только управление ожиданиями, но и структура.

Когда я говорю API, я имею в виду, как называются публичные / внутренние классы / методы и каков их уровень доступа (то есть, private / public / internal).

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

релизы:

  • Бета (то есть до 1.0)

    • может содержать несколько критических изменений API
    • могут отсутствовать изменения обратной совместимости между версиями
    • может иметь недостаток лака
  • Официальный (1.0+)

    • API заблокирован до следующего основного выпуска
    • любые внесенные изменения должны гарантировать обратную совместимость
  • Незначительный (бывший 1.1)

    • содержать исправления ошибок и / или реализации функций
    • может дополнять, но не убирать из определенного API

Если вы думаете, что API нужно укрепить в бою, то на некоторое время выпустите его как бета-версию. Это означает, что он доступен для использования, но не должен использоваться для производственного и / или критически важного кода.

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

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

Независимо от того, насколько хорошо что-то разработано, люди найдут способ злоупотребить или создать альтернативное использование.

Один из способов справиться с этим - заблокировать как можно большую часть реализации, используя средства доступа (т.е. частные / публичные / внутренние), но никакие разработки или инженерные разработки не дадут вам такого понимания, как предоставление кода пользователям.

На самом деле не имеет значения, насколько «идеальным» вы думаете, каким может стать ваш код, ваши пользователи докажут, что это не так.

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

В вашем случае вы закалены в битве с нуля, так что вы можете начать.


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

Реализация согласованной схемы ведения журналов будет важна до того, как код будет выпущен для производства, потому что вам понадобится способ глобально включать / отключать / фильтровать журналы. Кстати, в большинстве случаев ведение журнала действительно включает в себя импорт библиотеки и изменение выходных вызовов из Debug.WriteLine () на что-то вроде Logging.Debug (), Logging.Info (), Logging.Error (). Сам регистратор просто обеспечивает стандартную реализацию для конфигурации, фильтрации и более широкого диапазона схем вывода (ex-файлы, консоль и т. Д.).

Кроме этого, я бы посмотрел, чтобы получить код и использовать. Даже если только небольшое количество пользователей, чтобы начать.


1
+1 Re: ведение журнала - я настоятельно рекомендую TraceSource . Он не вводит никаких внешних зависимостей, поскольку является частью основных библиотек .NET и позволяет пользователям подключать прослушиватели и настраивать трассировку как через код, так и через файлы app.config.
Дэн Лайонс

4

Вот две вещи, которые я считаю ключевыми для выпуска программного обеспечения:

  • Точно знать, что вы выпустили
  • Управляйте ожиданиями

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

Зная, что вы выпустили

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

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

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

Управление ожиданиями

Документируйте ограничения и делайте их разумно очевидными для разработчиков. Хорошо, что вы их нашли. Люди часто лучше понимают, знают ли они ограничения в вашем программном обеспечении, особенно если у вас есть план по их устранению.

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

В будущем, по возможности, не меняйте API, это единственное, что может раздражать ваших клиентов. Помните, что исключения также являются частью API, хотя в C # они не являются частью документации метода. Это может быть возможным , чтобы улучшить исключения будучи брошенные на более поздний срок, но вам нужно будет поговорить с конечными пользователями и посмотреть , какое влияние это будет иметь.


0

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

Общая:

  • Вставьте нулевые проверки для параметров функции, которые не должны быть нулевыми. Это помогает мне потерпеть неудачу рано.
  • Удалите ненужные комментарии и закомментированные файлы. Это вызывает будущую работу.
  • Поиск любых комментариев "// TODO". Иногда я оставляю записи для себя. Иногда я забываю о них.
  • Запустите тест моего кода, используя производственную базу данных, где это возможно. Это помогает обеспечить все изменения базы данных на рабочем сервере.
  • Положите в обильное ведение журнала. Особенно для первоначального развертывания. На самом деле я сохраняю логирование до конца, потому что мой код на этом этапе обычно гелируется. Вы не хотите быть в ситуации, когда у вас происходит сбой, и вы говорите себе: «Если бы я только знал, какое значение Х было в это время». Попробуйте планировать заранее.
  • Попробуйте обернуть сторонние библиотечные вызовы в Фасады. Это позволяет легко менять библиотеки в будущем, а также предоставляет контрольный список того, что вам требуется от библиотеки.

.Net конкретно:

  • Убедитесь, что я вызываю Dispose () для одноразовых объектов. Я использую Code Analysis или FxCop, чтобы помочь найти случаи этого.
  • Убедитесь, что я открепляю все обработчики событий правильно. Это предотвращает утечки памяти.
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.