So, recently, I was challenged to understand the overall picture/design of the legacy system that we’re working on. I put up a fuss (read: work me is not the best me) because there was little to no documentation and the coding was convoluted.
At the end of the discussion, we arrived at a central idea:
- understand, document, and deliver the programming model in order to create a list of best practices for people to maintain your software in the future
Before tackling the problem, I want to define the terms.
What is a programming model, even?
According to web, Programming Models bridge some sort of gap between the design of a system and its implementation. Okay, so far.
[sounds like an interface or even a programming language, some higher level of abstraction]
Programming models exist independently of the programming language to implement as well as the defined APIs.
“Programming models are typically focused on achieving increased developer productivity, performance, and portability to other system designs.” 
Still makes sense. 5 minutes later, well, the rest of this paper isn’t helpful.
From a discussion with my peers, a programming model sounds like it boils down to a definition of how the code base should work and what the overall design principle was at the time of its creation.
A good place to start is to see how the folder structures are broken down by. Think about the whole system from a newbie’s point-of-view.
If I was completely new to the code base, what are the guiding principles that can help me to understand the overall system architecture quickly and get productive as soon as possible?
Maybe there’s a certain design pattern that you’re following or certain more complex parts of the application that need some more extensive documentation.
Whatever your answer is, it’s best to provide at least some idea to new contributors. Otherwise, when the code goes to crap (which it will), they would have never had a chance to do what was right.
I’ll report back when I have a better idea of what we end up doing for our programming model!
EDIT: 2018-04-20 17:18:55
Demo’d this to architect and other stakeholders and got a pretty good response. The context is that we are trying to build an application that is more functional in its design. Ideally, every process is stateless, but we do make note of possible side effects that occur.
I broke down the programming model into the small components that it is made of. This is the base class.
Then I moved on to the composition of those smaller base classes. For anonymity, they’re called
More composition class, zzz, of those not-so-small base classes. For anonymity, they’re called
Final rest endpoint.
Lesson learned: defining things in theory are much easier than actually implementing them, but at least we have a starting point.
References:  https://asc.llnl.gov/content/assets/docs/exascale-pmWG.pdf