2

Assuming I have the following objects (pseudocode for Ruby):

  • StringToXML with call method which accepts a String and returns an ExternalLibrary::XML::Document object (a data structure from a third-party library)
  • XMLToArray with call method which accepts ExternalLibrary::XML::Document and returns an array following some specifics

Should I wrap ExternalLibrary::XML::Document in a wrapper data structure, like XMLDocument and pass that around instead? What's the advantage in doing so?

5

In my opinion the balancing act depends on how well you can anticipate your software's design needs upfront vs. how well the library specifically fulfills them.

  • 3
    In my humble opinion, you can't really mess up with soft wrapping (encapsulation with a means to get the instance underneath). If you never need to do anything else with it, you've only lost the time it takes to make a wrapper class. In the contrary case, you've made your library far more backwards compatible for new changes. – Neil Dec 13 '17 at 8:05
  • 1
    That's my current feeling, but I wanted others opinion since JSON and XML have been around for so long. As I said in another comment, I need only 3 functionalities and exposing all document API seem excessive in my usecase. I also think about C, where you would at least create a new typedef of the XML struct if it comes from a third party lib. – Fire-Dragon-DoL Dec 13 '17 at 11:55
4

Really, it depends.

To take your XML example, consider how much refactoring might need to happen if you needed to extend or change your code to use object(s) represented by a different format; for example, wouldn't it be nicer if your code didn't care whether it was dealing with JSON, XML, Protobufs, etc?

On the other hand, you have to weigh the cost (in up-front development time, and in creating an additional layer of indirection) of writing an additional layer of abstraction compared with the potential benefit and likelihood of needing to support other data formats.

Also, consider unit testing - for example, how easy is it to use the library with unit tests? In the case of XML, it's generally easy to write some mock XML data, or provide a mock XML file. In the more general case, you might consider writing an abstraction layer if the library is likely to interfere with testing (for example, if it requires a remote endpoint or hardware device to work correctly).

If there's no significant impact on testing, and you can't foresee any need to add that kind of indirection, then consider the YAGNI princple, but also aim to at least structure your code in such a way whereby you can minimise the impact of future refactoring in case you need a new layer of abstraction later on.

Ultimately it comes down to up-front cost vs expected future cost. There are really two scenarios:

  1. The cost of writing more complex code up-front involves spending longer writing that code, and may involve future developers having a harder time learning how the code works, but it may also save buckets of time implementing future requirements.

  2. The up-front cost of throwing code together as quickly as possible can be heavily outweighed by the need to repay significant Technical Debt in future, and in the extreme case, risks creating a Big Ball of Mud.

While you shouldn't fall into the trap of writing elaborate solutions to simple problems, you should always be looking for ways to minimise technical debt; you can often achieve this by investing time creating automated tests. If you're struggling to decide, perhaps a more useful way to look at the conundrum is whether creating a new layer of abstraction will reduce the time it takes to write those tests.

  • Mhhh I would write unit tests no matter what. It's easier however to always create a JSON/XML document in the unit test (just run the function in the string), but even with the wrapper it's at most one additional line in the unit test. However I feel like wrapping might save long term problems in case you change library. I need 3 functionalities from the library: validate XML, get children of a node and get name of the node. Exposting the whole XML document feels excessive. Does it make sense? – Fire-Dragon-DoL Dec 13 '17 at 11:49
  • 1
    @Fire-Dragon-DoL That sounds reasonable to me. This feels like a good opportunity to abstract away some detail too. In particular, 'Validate XML' seems like it should be something which an abstraction could take care of, instead of exposing it as part of your wrapper interface. Personally, I'd look towards validating the document whenever the data is read from the source, and throwing an exception if the data is invalid. – Ben Cottrell Dec 13 '17 at 13:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.