Принцип найменшого здивування (POLA) та інтерфейси

Добру чверть століття тому, коли я вивчав C ++, мене вчили, що інтерфейси повинні прощати і, наскільки це можливо, не піклуватися про порядок виклику методів, оскільки споживач може не мати доступу до джерела чи документації замість це.

Однак щоразу, коли я наставляв молодших програмістів і старших розробників, почув мене, вони зреагували здивовано, що змусило мене замислитись, чи це справді річ, чи це просто вийшло з ладу.

Ясний, як грязь?

Розглянемо інтерфейс із цими методами (для створення файлів даних):

OpenFile
SetHeaderString
WriteDataLine
SetTrailerString
CloseFile

Тепер ви, звичайно, можете просто перейти через ці порядок, але сказати, що вам було байдуже ім’я файлу (подумайте a.out) або те, який заголовок та рядок трейлера включені, ви можете просто зателефонувати AddDataLine.

Менш крайнім прикладом може бути пропуск заголовків та причепів.

Ще одна може бути встановлення рядків заголовка та трейлера до відкриття файлу.

Це принцип розпізнавання інтерфейсів, який розпізнається або просто спосіб POLA до того, як йому було надано ім'я?

Зверніть увагу: не зациклюйтеся на деталях цього інтерфейсу, це лише приклад заради цього питання.

Один із способів, коли можна дотримуватися принципу найменшого здивування, - це розглянути інші принципи, такі як ISP і SRP , або навіть DRY .

У конкретному прикладі, який ви подали, здається, що існує певна залежність замовлення для управління файлом; але ваш API контролює як доступ до файлів, так і формат даних, що трохи нагадує порушення SRP.

Редагування / оновлення: воно також передбачає, що сам API просить користувача порушити DRY, оскільки їм потрібно буде повторювати ті самі кроки щоразу, коли вони використовують API .

Розглянемо альтернативний API, коли операції вводу-виводу є окремими від операцій з даними. і де сам API "володіє" замовленням:

ContentBuilder

SetHeader( ... )
AddLine( ... )
SetTrailer ( ... )

FileWriter

Open(filename) 
Write(content) throws InvalidContentException
Close()

З вищезазначеним розділенням, ContentBuilderне потрібно насправді нічого робити, крім магазину рядків / заголовків / трейлерів (можливо, також ContentBuilder.Serialize()метод, який знає порядок). Дотримуючись інших принципів SOLID, це вже не має значення, чи встановлюєте ви заголовок або трейлер до чи після додавання рядків, оскільки нічого в ContentBuilderфайлі насправді не записується до файлу до його передачі FileWriter.Write.

Це також має додаткову перевагу бути трохи більш гнучким; наприклад, може бути корисним виписати вміст у журнал діагностики або, можливо, передати його через мережу, а не писати його безпосередньо у файл.

Створюючи API, ви також повинні враховувати повідомлення про помилки, будь то стан, значення повернення, виняток, зворотний виклик чи щось інше. Користувач API, ймовірно, сподівається, що він зможе програмно виявити будь-які порушення своїх контрактів або навіть інші помилки, які він не може контролювати, такі як помилки вводу / виводу файлів.

Мова йде не лише про POLA, а й про запобігання недійсного стану як можливого джерела помилок.

Подивимось, як ми можемо надати певні обмеження для вашого прикладу, не надаючи конкретної реалізації:

Перший крок: Не дозволяйте нічого викликати до відкриття файлу.

CreateDataFileInterface
  + OpenFile(filename : string) : DataFileInterface

DataFileInterface
  + SetHeaderString(header : string) : void
  + WriteDataLine(data : string) : void
  + SetTrailerString(trailer : string) : void
  + Close() : void

Тепер має бути очевидним, що CreateDataFileInterface.OpenFileпотрібно викликати для отримання DataFileInterfaceекземпляра, куди можуть бути записані фактичні дані.

Другий крок: Переконайтеся, що заголовки та причепи завжди встановлені.

CreateDataFileInterface
  + OpenFile(filename : string, header: string, trailer : string) : DataFileInterface

DataFileInterface
  + WriteDataLine(data : string) : void
  + Close() : void

Тепер ви повинні надати всі необхідні параметри наперед, щоб отримати DataFileInterface: ім'я файлу, заголовок та трейлер. Якщо рядок трейлера недоступний, поки не будуть записані всі рядки, ви також можете перемістити цей параметр у Close()(можливо, перейменувавши метод на WriteTrailerAndClose()), щоб файл принаймні не міг бути закінчений без рядка з трейлером.

Щоб відповісти на коментар:

Мені подобається розділення інтерфейсу. Але я схильний думати, що ваші пропозиції щодо примусового виконання (наприклад, WriteTrailerAndClose ()) опираються на порушення SRP. (Це те, з чим я неодноразово боровся, але ваша пропозиція здається можливим прикладом.) Як би ви відповіли?

Правда. Я не хотів більше концентруватися на прикладі, ніж потрібно, щоб зробити свою думку, але це гарне питання. У цьому випадку я думаю, що я б назвав це Finalize(trailer)і стверджую, що це робить не надто багато. Написання трейлера та закриття - лише деталі реалізації. Але якщо ви не погоджуєтесь або маєте подібну ситуацію, коли це інакше, ось можливе рішення:

CreateDataFileInterface
  + OpenFile(filename : string, header : string) : IncompleteDataFileInterface

IncompleteDataFileInterface
  + WriteDataLine(data : string) : void
  + FinalizeWithTrailer(trailer : string) : CompleteDataFileInterface

CompleteDataFileInterface
  + Close()

Я б насправді цього не робив для цього прикладу, але він показує, як слід вести техніку.

До речі, я припускав, що методи насправді потрібно викликати в такому порядку, наприклад, щоб послідовно писати багато рядків. Якщо цього не потрібно, я б завжди віддав перевагу будівельнику, як це запропонував Бен Коттрел .