1

Our current business process is that the domain experts will write down the business logic in a Word document, and developers will try to reflect those logic as closely as possible with the implementation.

This process violates the DRY (do not repeat yourself) principle, and thus creates many problems that are associated with violating DRY principle.

There is no programmatical way of determining if the change in the domain document is correctly reflected in the code base. This forces very close-knit communication between the domain expert and the developer, which causes other problems such as the document resembling more of the tech specifications rather than the domain specifications and frequent meetings if any part of the document needs to be updated.

Note that I am a developer, and I am not looking to introduce a solution that requires an adoption of a software approach by anyone but me. I am trying to find a simple solution that can be handled by a single developer.

I've done my research and have encountered some suggested solutions such as domain specific language or domain driven design, but they don't fit my needs for the following reasons:

  • DSL: This requires the adoption on the DE's part to use the DSL. I can use DSL to implement the domain logic using DSL, but this doesn't resolve the underlying problem of separation between domain document and implementation. Also, I do not want to limit domain expert's ability to express domain problem to specifically DSL. I want them to be able to use natural English.
  • DDD: A bit better than DSL in that only the ubiquitous language needs to be developed, but this still requires explaning the concept of DDD to everyone involved.

In essence, I am looking for a simple solution that can be contained by a single developer. One ideal solution I was thinking was have some tool that can somehow annotate a section of the documentation to the specific code implementation, so that at least we have a brief visual cue of how well covered our documentation is.

THIS USER NEEDS HELP
  • 141
  • 6
  • The paradigm you are describing has a name: "literate programming". (https://en.wikipedia.org/wiki/Literate_programming). It's a lovely idea. It hasn't caught on. – Eric Lippert Mar 10 '18 at 00:03
  • When I was writing the Roslyn semantic analyzer I simply cut-n-pasted big chunks of the specification right into the comments. Is this repeating yourself? Sure. Is there then difficulty because you have three things to update when the spec changes? (the spec, the code, the comments) Yep. The question is whether the added work is worth the cost; I believe it is. – Eric Lippert Mar 10 '18 at 00:05
  • @EricLippert Thanks for introducing the fascinating concept! But isn't literate programming basically what Jupyter Note does (it even seems to be listed under `Tools`? But regardless, the main problem would be that this prevents any form of organization or optimization of the code base since everything needs to be laid out within the documentation itself. If the program's complexity rises, it seems LP will become a giant `tangle` without the capability to organize the code. – THIS USER NEEDS HELP Mar 10 '18 at 01:04
  • @EricLippert I will have to disagree that copy-paste would be an appropriate solution. As you mentioned, this further violated the DRY principle, and as Pragmatic Programmer notes, one of the three document **will**, not can, get outdated. It will be a matter of time. Since the comment depends on the code and the documentation, and since the code depends on the documentation, I am wondering if there is any tool that can automatically link this relationship. – THIS USER NEEDS HELP Mar 10 '18 at 01:07
  • @THISUSERNEEDSHELP: One nice thing about working on the Roslyn semantic analyzer is that the formal specification changes independently from the code-base. The copy/pasted specification only needs to be touched once per spec update, and it can be versioned so that anyone reading it will know which section of which version of the specification it refers to. Thus, the comment will be out-of-date if the spec changes, but won't be wrong. This sort of thing only works well if the specification is highly formalized...which is generally a good idea for compiler design. – Brian Mar 12 '18 at 13:12
  • Disclaimer: The above comments are my beliefs, but they aren't backed by experience working on the Roslyn semantic analyzer. – Brian Mar 12 '18 at 13:13
  • @Brian: Indeed. One of Anders' guidelines for the C# specification is that it *not* contain "higher math"; generally the algorithms of the compiler are not described, and where they are, they are expressed in English, not in any sort of formal metalanguage. When I was briefly on the ECMAScript 4 committee, the spec maintainer had a metalanguage for the specification, and an interpreter of the metalanguage written in Lisp, and so the specification could be actually executed. It was a nice idea but that effort ended up abandoned for a variety of unrelated reasons. – Eric Lippert Mar 12 '18 at 17:55

2 Answers2

1

Our current business process is that the domain experts will write down the business logic in a Word document, and developers will try to reflect those logic as closely as possible with the implementation.

This process violates the DRY (do not repeat yourself) principle, and thus creates many problems that are associated with violating DRY principle.

The problem here is retaining this word document as if it has meaning beyond when the programmer first consumes it.

If the programmer is creating a DSL or a ubiquitous language in DDD then the business logic should be something a domain expert is comfortable inspecting directly. It should also be free of anything technical that distracts from focusing on high level policy.

We're not at the point where you can force the domain expert to write actual business logic. But if you do it right they can read it and tell you if you forgot something or are doing something wrong.

So yes, that word document will get outdated. That's fine. It shouldn't be kept current. The business logic should be something your domain expert can print and doodle on. It shouldn't be something they author in word.

Community
  • 1
candied_orange
  • 102,279
  • 24
  • 197
  • 315
  • If I am not mistaken, is this the business process you are suggesting? 1. Domain expert maintain the Word documentation, 2. Developer maintain the DSL based on the Word documentation, 3. Domain expert reviews the DSL to verify that the Word documentation aligns with the implementation. – THIS USER NEEDS HELP Mar 13 '18 at 20:34
  • In other words, we are only surfacing the DSL to the expert, not the actual implementation, and DSL does the implementation underneath? – THIS USER NEEDS HELP Mar 13 '18 at 20:56
  • Yes and "maintaining" word documentation would be a mistake. Once the DSL or domain logic is surfaced the word document can be discarded. In fact, since it's so tempting to retain it it's likely not a good idea to let it be created in the first place. It's better to gather this info in interviews and whiteboard discussions. That way when your done there is a single source of truth. – candied_orange Mar 13 '18 at 21:53
  • But what if other people other than the domain expert and the developer need to consume the documentation? Our service provides a validation service, so we need to distribute the documentation to others in *natural language* so that it's clear what we are doing to validate certain service. – THIS USER NEEDS HELP Mar 13 '18 at 23:44
  • That's a specification. Not a list of business rules. – candied_orange Mar 13 '18 at 23:49
  • Regardless of the terminology, if the domain expert writes up the specification, I was just wondering if there is other established practice that can link spec to the implementation. I do *not* want to make specification describe the code as you mentioned, but some kind of system that can tell that if a certain part of the spec is changed, then, the corresponding code needs to be re-examined, and vice versa. It doesn't have to computationally verify the correctness, but *link* spec and implementation – THIS USER NEEDS HELP Mar 14 '18 at 00:33
  • There are probably some elaborate systems for doing that. We used to do it with comments next to the business logic code that mentioned the requirement number. Not a great system if you ever renumber your requirements. You could try giving your requirements unique names.Or better yet ensure the requirements numbers are meaningless so no one ever tries to renumber them. – candied_orange Mar 14 '18 at 03:03
0

I honestly don't see an issue, in terms of process, with your current system. All that needs to be done here is a simple paradigm shift in how you guys treat and think about the documents that outline business rules.

The first change here is to forget about using these documents as some sort of analogue to code documentation. You are bridging a gap that needn't be bridged, and doing so is to everyone's detriment. Domain experts document the business requirements and processes that are important to the business. Other than using the Ubiquitous Language (which is formed at this level and permeates downward), these documents have nothing to do with your code base or it's implementation. Code documentation is technical by nature and shouldn't be mixed with rules that span process.

It seems like you guys are trying to find a middle-ground between Domain Expert and Developer in a way such that the experts can create some sort of pseudo-code that get translated into actual code. Additionally, you would like to impose rules on that process to ensure that the translation is not only happening, but is also correct. At that point, why not just have Domain Experts write the actual code?! The reason your job exists is so that Domain Experts can focus on the domain and you can focus on the code (the technical implementation). Currently, both roles seem to be focusing on the wrong thing (I suppose this is why you want an automated solution).

The second shift is, put simply, the business documents cannot be changed, only replaced. When a new document replaces an old document, the code base is changed to reflect the new rules. Fundamentally, this is just version control.

There will never be a good way to programmatically know if changes to a business document have been reflected in code (forget correctly). I'm getting queasy just envisioning the mess such a system would create. Better solutions can be found by taking a look at the process itself (introducing "tickets", for example). If this is such an important part of your business process, surely adding some simple infrastructure to manage it will be worth while. Including an automated testing suite can be very helpful as well.

And for what it's worth, close communication between domain experts and developers is a good thing.

user3347715
  • 3,084
  • 11
  • 16