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

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

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

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

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

Ответы

Ответ 1

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

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

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

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

Ответ 2

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

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

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