The Joy Of Coding – Class and Sequence Diagrams
Okay, so you are an ABAP developer? Your mission, should you choose to accept it, is to change our SAP ERP Business Suite according to the specification from our business experts.
I assert the developer’s mood affects the code quality. I discuss a process where tools to display the topology and the coupling of ABAP programs bring back the joy of coding.
Joy of Coding
I like the verb comprehend, as it is etymologically be linked to incorporate. For me it conveys the feeling of being the owner of something after I grasp it for the first time.
As developer exploring a problem space while trying to implement a feature, they are times where our confidence improves, we know we are on the right path, we comprehend the system feedback, we feel the joy of coding.
This sense of achievement is a feedback loop in the development process. Without it, the next steps are speculative and FUD (Fear, Uncertainty and Doubt) suck the joy out us like dementors.
Of course we feel more productive in environments where each input leads to near instant response. After an initial training phase, the tools get out of focus the experience is one of nearly telepathic conversation with the system, getting immediate feedback… We want to be in this mode.
e.g. format a text or HTML in a WYSIWYG editor, or develop a script using a read-eval-print loop (REPL), e.g. in this LISP Interpreter in ABAP. I can quickly try many options for a small chunk of code and get the feedback. I can run a test for each line and let the result guide me.
This is a bottom-up approach to coding. The code grows with focus on the requirements.
Most ABAP coding is highly integrated with the code of the SAP system, so we are often performing integration tests with a lot of time between input and feedback. This process has a higher risk of FUD and code and pray style of work.
There are things we do, like testing, debugging, that help us produce working code. These activities bring joy to the developer. The feedback is there and the next steps can be planned. But we still have issue with quality:
Real programmers can read pages of ABAP without getting confused, but we should have learned modularity based on abstraction is the way things should be done. But go on CSI ABAP and look at the top ABAP crimes. And why do produce code with a lot of globals, if shared mutable state is evil?
The Pursuit of Happiness
- The process has to be changed so that the quality measure brings joy.
- We have to measure the quality of our code to improve it.
We study the specification and in doubt, question our initial interpretation and enrich our knowledge of the business domain. We are happy when we can explain the requirement, the specification and how to perform the end-to-end tests.
Using the agile motto first make it work, then make it right, we can aim at the simplest design that could possibly work.
Some important decisions about the code structure have to be made now while some insights will be gained later. Further, the ABAP language with its 700+ keywords provides multiple possible valid translations of the same concept.
We are happy when we have created a specific idea, how things should to be divided.
First Make This Work
Do not expect a silver bullet, You Can’t Improve What You Can’t Measure!
My proposal is to create a class diagrams and sequence diagrams after every change and check that the diagrams evolve to some useful documentation you could use to explain the code to a peer. If discrepancies between the idea and the documentation of the actual implementation appear, changing or restructuring the code should be cheap at this stage.
At the end of this process, the specification is rewritten in the more formal ABAP language. We can showcase working code that passes the first smoke tests. Thus we are happy and can continue with a boost of confidence in our understanding of the requirements and an enhanced self-esteem.
Then Make It Right
This is the part where we care about the quality of our code. What is the soul of our implementation? We can now apply our know how to massage the code in a simpler form.
We can request additional feedback code reviews, read books, blogs, even SCN to challenge our ability to translate subtle nuances in the requirement into the design needed to solve the task.
We are now used to use our documentation artifacts (class diagram, sequence diagram) to communicate our design with peers. Eventually, we can create a model that the business expert will understand and discuss. We are happy.
Static Code Analysis
Analysis of the static code starts with the extended program check and the code inspector. But to get a topology of our code, its structure, the UML class diagram generation integrated in workbench transaction SE80 is the tool of choice.
The class diagram generated from the code structure can be compared to our idea of a separation of concerns. Do we recognize our intentions in the modularization units? Can it help explain our design to a peer? In short, is it useful?
Dynamic Code Behavior
To analyze the run-time behavior, we instrument the code to save additional information (trace) while it is running. At the end, we can reverse engineer the execution path based on the trace data. Since Netweaver 7.02, transaction SAT has supersized transaction SE30 as the tool that implement this dynamic program analysis for us. I refer to a series of blogs to introduce it
One result we are interested in here is view of the cross-coupling. This allow to discuss if the interfaces between the different actors in our code.
At InnoJam in Sydney 2011, Chris Paine et al realized the data collected could be re-used in any custom logic. His next great idea was not to generate the output himself. He settled for PlantUML for graphic output.
In this the part I point to my own work: I have integrated the PlantUML web service to generate the graphic output in the background, so we now have a seamless sequence diagram generation ABAP Trace to PlantUML Sequence+Diagram.
The new tools allow the creation of a topology of the program and a sequence diagram of the program execution on the fly. This enables a new feedback loop that can be embedded in the coding process.
As we learn more, each new iteration can take advantage of the deeper insight in the business requirements and the technical solution. We expect an improved design, better code quality and the Joy of Coding.
Even under a process dominated by FUD, we now have something that can help enhance the documentation. At this stage we previously were happy to have something that work and we rushed to ship it. We should now have a somewhat better know how transfer of our knowledge and the constraints faced for the next developer.
So by using inexpensive tools to document the code, we can at least include some additional UML views and better decide what should be commented on to reflect our intentions.
- Object Oriented Analysis and Design with Applications (3rd ed.) by Grady Booch et al
- Practical Object-Oriented Design in Ruby. An Agile Primer by Sandi Metz (cf. POODR)
- Refactoring, Improving the Design of Existing Code, by Martin Fowler et al,
- Elemental Design Pattern, by Jason Mc C. Smith
- Growing Object-Oriented Software, Guided by Tests, by Steve Freeman and Nat Pryce