Документирование интерфейсов и их реализация [закрыто]

Question

Я украшаю свой код C# комментариями, чтобы можно было создавать файлы справки в формате HTML.

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

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

Должен ли я создавать/документировать пользовательские исключения, чтобы разработчики интерфейсов выбрасывали их вместо исключений платформы?

Надеюсь, это понятно!

Спасибо

РЕДАКТИРОВАТЬ 4 января 2010 г.:Я решил написать сообщение в блоге об этом и пользовательских исключениях в .NET по адресу http://blog.mikecouturier.com/2010/01/creating-custom-Exceptions-in-net-right.html

Answer 1

Я не уверен, что полностью понял ваш вопрос (и я разработчик Java, а не C#), но, похоже, вы спрашиваете о том, что по сути является проблемой полиморфизма:если кто-то использует метод интерфейса, который объявлен как выдающий X и Y, что произойдет, если реализация выдаст Z?

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

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

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

Answer 2

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

Однако не создавайте их без необходимости: если существует исключение .Net Framework, описывающее ваше состояние ошибки, используйте его.

Что касается документирования для разработчиков, вы можете использовать раздел примечаний в комментариях (при условии, что вы используете комментарии XML), чтобы описать такие вещи, как, например, то, как вы ожидаете, что разработчики будут делать что-то.Очевидно, что это никоим образом не является обязательным, но может послужить полезным руководством, когда разработчик начнет использовать ваш API.