Personal Insights
Building the next CD-Player, or: Invention vs. Innovation
This blog tells a short story about what can happen when we focus too much on a detailed solution to a specific problem – while time moves on.
An Age-Old Problem
That specific problem dates way back to the late 80’s, when I was leading a Software Development Team in the German Army. Every 3 months I had my pick to get 1 or 2 new team members from a batch of bright-eyed albeit inexperienced young people to turn them into COBOL (of all things!) programmers. Of course, in turn I had to let 1-2 of my current team go; their time with the army was up. So I waded through lines and lines of code to get the new guys started where the old ones left up.
Of course, everyone had their own style of coding, and (more or less) documenting, and there was a lot of time wasted trying to make sense of it all.
Turn the page… Years later, as ABAP Lead with an SAP consulting company, every time I had some new developers coming in, guess what… same procedure. So I did what all of us did back in those days. Established the dreaded ‘Documentation Guidelines’ and forced my poor guys to spend a good portion of their time writing up stuff about their work. Which they did, more or less.
Nowadays, as an ABAP Freelancer, coming into a new client project – time is money, and what happens? First of all, I have to dig through whole labyrinths of code to find my way to my new build site. Comments? Documentation? Well… you know.
A Nice Try
Some things never change; and I wished there is a way to automate that kind of busywork – in a way that makes sense for the reader and does not depend (too much!) on the Developer / Author. Nothing against things like ABAP Doc – but still, the developer has to spend some effort to make comments, and talk about their work…
But wait: Does not, by definition, the Development Object (and it’s runtime environment; technically speaking…) contain all the information it needs to run? The developer just put it there! (And according to the 1st Law of Thermodynamics it cannot get lost… unless we’re beyond the Event Horizon of a Black Hole ?). So it is only a matter of getting it out of there.
So I made some time, sat back thinking, and came up with a design for a tool that analyzes the Development Object itself (source code, metadata, structure, and yes, even including comments if they exist) and create a Technical Document that I thought I could use to at least gain an initial understanding of what I’m up against, when I see an unknown program (or Class, or Transaction…) for the first time.
Then I made some more time, got down to business, locked myself in and started building. Without looking left or right, and never bothered wasting time to chase the latest trends in technology. When I finally had something halfway workable, I looked up and stepped out of what I now realized was some sort of a nasty Time Machine… Years had passed, and my prototype is now all but obsolete.
I had built a ‘Better CD-Player’ and brought it into a world where everyone is streaming music… ?
Food for Thoughts
Now, what do we learn from that little story? Several things come to mind:
- Inventing nowadays is just for large teams and companies with the money and manpower to keep up with evolving technology. Hm… not a nice thought.
- Due to recent improvements in tools and techniques, such as ABAP Doc, ‘Clean Code’, GitHub and so on the root problem has gone away. Really?
- I just did not do a good enough job nailing down the requirements and designing / building the solution. Kinda embarrassing – but, well, nobody is perfect.
- A combination of some sort of all of the above?
- Anything I have missed completely?
Discuss.
All the best,
Mike, ABAP-OldTimer
Another old-timer here Michael: I was always 'lukewarm' about technical specs and in my experience they are never consulted (not by me anyway). I always thought it was better to just look at the code: with good developers, you always know what is going on.
What I never fail to look at are the design overview notes made by the developer, usually attached to the functional design. These often have precisely the info you need to understand the tricky parts.
Nice blog, and thought provoking
Cheers
Ged
Yea, me too - I always 'make do' by looking at the code, and everything else someone wrote. But honestly, in my mind this is just a work around, and not a solution. We are just so used to it...
From my experience: I think an arc42 styled document is good to give a clear idea to all stakeholeders what should be developed. After that you can forget the document 🙂 The content is outdated by the development. Then you can only tell from the source code and the development objects, how the original idea was implemented. There was a function to create something like a "class diagramm" from ABAP Workbench. This was handy because it analyzed the development objects and then you had a first overview. But I'm not sure if it is supported today.
Of course any document that is independent or disconnected from the Development Object is outdated the moment of the first change. So any tool needs to be able to analyze the Development Object ad-hoc and as-is. As to class diagrams, there are some attempts like the report UML_CLASS_DIAGRAM or class CL_UML_CLASS_SCANNER. I tried to include them into my design but somehow never really got them to work. But that is where it should get started, I believe. There are also many more blogs to that topic that I am currently exploring. One example: https://blogs.sap.com/2013/08/21/auto-generating-uml-diagrams-from-abap-code/
Thought provoking blog Michael Koehler. I believe the initial purpose of having functional/technical specifications apart from the code was to make sure any developer can read and understand the development and accordingly make the change. But this thing has/had many flaws
So to summarize i feel their is no easy way to understand our golden ABAP code. We have huge efforts going on in this direction such as Clean code, git etc. but still the need for such a tool will always remain as no two developers are the same.
I hope more and more developers make this switch and make sure their code is readable
Nabheet
Nice blog !
J.
Interesting blog, Michael, thanks for sharing!
In my view, your story is not one of a failure. You saw an opportunity for innovation (or invention?) and you used it to create something new. Even if in the end your work might have gotten outpaced by the rest of technology and someone else's inventions, that's fine. I bet you learned something new during this whole endeavor and, most importantly, you tried. All this while many people leave by Homer Simpson's principle that "trying is the first step towards failure". 🙂
Personally, I don't mind at all writing the documentation and my documents are always excellent. 🙂 But, as others noted, any specification or documentation quickly becomes obsolete. That's why I believe that the only offline documentation should be only the top-level design overview of complex projects, interfaces, and such. Within the system, self-documenting code (with the few meaningful comments) is the way to go. No tool can replace that.
Unfortunately, there still seem to be some non-believers in that and it's not something that automated code check can easily identify. If a company has a manual code review process then this definitely should be enforced strictly.
It's interesting that just today Matthias Steiner wrote about building code like a factory. I agree that this is where we are heading. So how would anyone assemble code from the parts that require reading a manual before being used? I suspect the ROI on the self-documented, clean code will be increasing exponentially for every SAP customer.
Yeah, that definitely sounds like Homer Simpson - I'd rather go with "if you try something new, you may fail. But if you don't even try, you have already failed!". I don't know who said that; kinda sounds like something Sun Tzu would say...
Also interesting you mention Matthias' blog - I left a comment there, too ?. On what I believe being an ABAPer is all about.
Best,
Mike
Hey Michael,
maybe I missed it, but you haven't told us, what exactly it is you build, have you? Can you?
-> Maybe it's still useful in some field you don't think of.
To stay in your CD-player vs. streaming picture:
(some) people do now realize that is has a certain value to own a physical object (e.g. a CD) that will not be easily taken away from you and will also work #offline.
best
Joachim
Hi Joachim,
Thanks for your interest - I see your point; even vinyl is making a come-back now- I've still got approx 150 albums...?
To your question: What I have built is a tool (working prototype, to be exact) to help automate the dreaded task of writing technical documentation. It analyzes the ABAP Development Object (Program, Class, Transaction, Report, etc) and creates a structured 'skeleton' Tech Doc out of it and some templates, renders it in SmartForms. I have done this as a 'one-man show', over the last few years.
Last summer I was looking for a partner to work with me and turn it into a product to market. That was when I found that technology has basically passed me by - with ABAP Doc, ABAPGit, and especially the Code Inspector and Eclipse the room for a tool like mine is very limited.
If you are still interested in more, please feel free to explore here: http://www.birmic.com/recent
All the best,
Mike