What’s missing?
The real costs of technical debt, how to recognize its stifling impact on future development, and when to ditch it.
2 Likes
Filling in the gaps in the existing doc is really not the intent - since almost all of the docs assume appgen use and our app is hand code. However, I get your point. The gap discussion is mostly about gotchas such as the ones Carl pointed out. The core of it would be to cover the items listed as a language features and how we use them in the context of our apps. Not all of the things on this list are pertinent to us, but I didnt want to limit it and reduce the usefulness of the outline for others.
Also - I havent organized it yet. Youre right that the list is currently a scatter of topics that definitely requires organization:)
What would be interesting to see…
If you come up with a guide to how you write a hand-coded program, with an explanation of the accept loop, event handling, routines, procedure calls, display of results and so on…
Is it possible to write a document that uses that as a base and explains how the hand-coded approach is translated in the ABC classes that then becomes useful for someone who has to learn how to efficiently modify an appgen ABC app to do what it needs to do?
It would be nice to think that understanding the concepts from a hand-coded app would help and be a good foundation, but I’m not sure that it would be.
You can try to read about it, but better to try to write the code, build and revise…
Opening a working hand coded project and seeing the code is a good start. Modify it, build, test. From my repos look at: Holiday-Calculator, OpenFileForTest, ClipboardEnumViewer, LIST-Style-Checkbox, Clarion-Root-Find. IMO Clarion is nice to hand code. I do it all the time starting with a blank page.
There is good non-ABC code generated by the templates you can look at. Create a Legacy template APP and use just the Window Template. Add some controls and embed code then Generate. The Embeditor shows every possible so too much, better to view the Module to see the minimal generated source. Legacy does tend to have a several routines I don’t use hand coding.
As I describe for Legacy create an ABC APP. Add just a Window template procedure with a few controls and generate. Right click open Module shows the generated code that will be fairly minimal. That would be what you would hand code. In hand code you would need the INCLUDEs and Project defines.
I have thought about trying to write some hand coded programs using ABC but so far have not. In the examples there were some hand coded ABC written by DAB like ABC Convert and Call Tree.
One of the things I frequently find lacking in old school docs is the why that accompanies the what. Some devs dont need those things, but a lot of them do. They show examples of what to do, but dont tend to explain why to do it - and do it a certain way. Hopefully this doc will include some of that. We’ll see:)
hmm - then I suppose the logical extension to your training / documentation will need to be on all the functions and libraries of your own code that exist in the app.
Ultimately this can be more of a challenge than the Clarion language, because at least with the language there are online communities and people to ask. But “internal” functions are often duplicated, or just rewritten, because the new developers don’t know that the functions already exist.
You can see this in Clarion itself - in Cwutil.Clw there’s a function (File Exists) which was clearly written by someone who did not know that the EXISTS language command, um, existed.
Our record (in an inherited system, worked on by many developers) is 23 functions that were all “the same” (scattered across different apps) - although in that case they’d be cloned one from another in order to make a “small change”. Obviously the program used all 23 though - I mean, why wouldn’t it 
1 Like
Documentation encompasses different topics, and ideally these topics should be covered separately.
a) Tutorial (ie learning the basics, some sort of progressive run through). this would include some Why, but likely not much so as not to overwhelm the learner.
b) Explanatory (more detailed learning, showing common tasks, ideally with comments.) This is probably the best “why” part.
c) Reference (for each function / method - explaining the parameters of use - what it does, side effects and so on.) “why” here can be tricky because by it’s nature this is fundamental, and the “whys” are typically at a higher level.
d) Examples - working (commented?) blocks of code that can be inspected, fiddled with, and so on. Often some whys in the comments here.
I know our accessory code is far from the above ideal, and our actual apps code doesn’t even get onto this scale. It’s a time/resources thing. All we can hope to do is keep improving it wherever and whenever possible.
I get it, but it is what it is. Much of this code predates ST (for example), and similar things that didnt exist when those parts of the code were first written. Even so, with 1.5-2MM lines of code, things that work tend to be left alone.
So, I wasn’t suggesting you change, but rather following the thought through -
given the size of this project, learning clarion will be a small part of the puzzle. Learning what functions already exist in the program, and how to use them, may be the bigger challenge. If your app is anything like ours then none of this is documented from a “new developer” perspective, so passing on that institutional knowledge of what functions exists, and what they do, is likely the harder part…
CwUtil FileExists() can do (‘*.clw’) because it uses FindFirstFile() so supports wild cards that RTL EXISTS() does not. I usually write a little function using Directory() when I want wildcards, but FindFirstFile() would be much quicker loading just the first file.
I think the name is misleading because it will find Files and Directories. Almost always I want to know specifically one. If a File named ‘EXPORT’ exists that will cause problems creating file ‘Export\pay,csv’. The easy way to do that (w/o wildcards) is with GetFileAttributes like this: ExistsDirectory() or ExistsFile() using GetFileAttributes() instead of Clarion Exists() · GitHub
1 Like
FindFirstFile has (or had?) some gnarly issues on networks. At one point, it was completely not dependable for network drive resources - but I dont know if that has been fixed.
Yes, exactly.
The idea is meeting all of that somewhere in the middle, The part of the curriculum I didnt share is specific to the app and the regular duties of adding to / maintaining it.
Exactly (all of that). I remember first running into this on Win2k.
True, but we dont participate in that nightmare:) Unshared TPS opened by 1 person, or SQL (via REST).
REST lets us use the same code for local or WAN installs with no drivers and very little firewall issues. It also avoids opening databases to the world. WAN performance is usually better than remote SQL and a ton safer.
I mean a REST API - but not those. Ours is proprietary to us.
Topics not mentioned above: GPF’s and Version control
- GPF: How to track them down: Hunting down nasty GPF's
- GPF: How to increase crash log information: How to improve the Call Stack when your program GPFs
- Clarion debugger.
- Version control: GIT
- The importance of: Save your work
1 Like
Thanks Eric. Git isnt on the list because it is assumed that any experienced developer using another language would already know it. I have added this assumption explicitly to the audience section in order to clarify that expectation. The GPF stuff is definitely important.
one GPF to describe - as it’s UNDOCUMENTED
when you have a class with a module attribute (typically added to code via an INCLUDE)
it’s REQUIRED that the class appears at a static scope (which is to say global or module scope)
Otherwise, it will compile fine, but will GPF as soon as you touch the class
That’s true with API/external prototypes too.