Clarion Training Plan Outline

I’m working on an outline for a training plan for new hand code devs for our big app who do not know Clarion. So far, I’ve assembled this list of topics.

Audience:

  • Developer(s) who know a programming language other than Clarion. This outline doesn’t have to teach programming, Git, or similar fundamentals.

  • Developer(s) who have completed the C11 tutorials and reviewed the examples. The examples are all / mostly appgen, but I figure it cant hurt much to review them.

Outline so far:

  • Accept loop
  • “Hand-coded” vs application generator (“appgen”)
  • Drivers
  • Flexible data types
  • Window formatter and window control types
  • Report formatter and report control types
  • Debugger vs Debugview++
  • OCX use
  • Use variables
  • Display update
  • Field equates
  • Property syntax
  • Cycle to short circuit events
  • Member attribute
  • Conditional omit / compile
  • Logical expression short circuiting
  • Pictures
  • Thread attribute
  • Classes
  • Queues
  • Type attribute
  • Queue as a class property
  • DLLs
  • APIs (calling into dlls)
  • Working with VSCode / Sublime text
  • Prefixes vs dot notation
  • References
  • Post & notify
  • File and queue buffers
  • nuances of CHOOSE
  • Special notations in String literals
  • Program structure
  • Map
  • Procedure
  • Code
  • Routines
  • Oddities of scope
  • The RED file
  • Builtins.clw and Win32.lib
  • ? In column 1
  • START and parameters (not the CLR stuff - but how they can be leveraged)
  • Implicit variables (dont use them, sparky)
  • Field equates / the use of std Clarion equates
  • Use of EQUATE in general for making code understandable. See also “what MG says” :slight_smile:
  • Who / What / Where

Documentation sources for Clarion devs

Open source / free resources

  • SourceTree
  • Github desktop
  • KSS
  • Clarion projects on Github

Again - this is hand code, there will be no discussion of the appgen, templates, or any of that.

What’s missing?

LOOP X=1 TO limit
Loop ends with X=Limit + 1
Limit as an Expression is evaluated Once before Loop starts.
WHILE or UNTIL are alternatives that are evaluated every loop

CASE - a single OF executes, there is no Break like in C. Each OROF can never code that executes

These things vary by language

Thanks, Carl.

FWIW, I’m primarily focused on what a dev needs to learn that isnt part of the language reference, tutorials, etc. I dont want to duplicate the language reference - even though it clearly needs significant improvement and better examples that actually compile:) Non-obvious nuances, however, are definitely in-context.

What is the backend?

In this instance, either TPS or REST depending on the deployment platform, but I wouldnt let that restrict your answers. Ideally this will be of use to anyone.

If SQL was involved, I certainly would recommend knowledge of PROP:Alias and other related techniques for queries from Clarion.

In addition to field equates I would include the use of std Clarion equates and EQUATE in general for making code understandable.

1 Like

When learning to write hand code it is helpful to have a Scratch Program with a few things you commonly use like a WINDOW and ACCEPT. That way you can drop a little bit of code into the Scratch framework and build a working test quickly. My Scratch program:

If you’re trying to learn to write StringTheory calls I have several tools and an ST specific Scratch program. Get the code tested and working in a small context before pasting it into production. Paste into Clarion Test to continually test.

The Write Theory tool can lets you click on any call in the INC file, enter the parameters in a Form and generate the code. Help button opens Cape Soft help page.

I have a Scratch for Reports that is mainly for working out PROPs and other code to manipulate controls and details to do unusual things. Its nice for submitting bugs on PTSS with minimal code. https://gist.github.com/CarlTBarnes/29f78a2ca43813e83489dc62a4d5e0c0

1 Like

In our case, there are roughly 1.5MM lines of examples. Any new code is going to be built from a template (not a clarion template) for a module that has been gutted of non-essentials. Also, these devs dont have StringTheory at their disposal, other than via a DLL they call now and then (and the purpose is not to get StringTheory results).

But… for everyone else, this would surely be useful.

Hi Mark,

I’d suggest adding WHO, WHAT, WHERE to the list (aka Reflection).
Perhaps with reference to extended attributes (A Proposed Convention for the Extended use of the Name Attribute)

Why not? (Genuinely curious). It works well in hand-code applications, and I suspect programmers coming from other languages would be disappointed with the limited String functions in Clarion.

No ST because there are no Clarion 3rd party tools in this hand code app - other than OCXs we use. That of course does not count my license mgmt / file sync DLL, which uses NT, ST, WE & jFiles / xFiles.

Who/What/Where - good idea, thanks.

so … if you contracted me for a month, I could write you a decent first-party, string-handling library that all your devs could use :slight_smile:

I suppose so. I think the deal is that they wrote their own routines years ago, so…

Hi Mark,

I don’t think you can have a coherent training plan that is just trying to fill in holes in the existing Clarion documentation. Here’s my attempt to structure at least some of your topics into something that makes more sense (to me):

Getting stuff in and out of windows
Window formatter and window control types
Use variables
Display update
Field equates
Pictures
File buffers
Prefixes vs dot notation
Lists and queues
Queues
File and queue buffers
Accept loop and events
POSTing events
Cycle to short circuit events
Using NOTIFY
Program structure
Member attribute
Map
Procedure
Code
Routines
Oddities of scope
File declarations
Thread attribute
Type declarations Type attribute
Classes
Properties and members
Inheritance
Queue as a class property
Persistent data
Drivers

  1. “Hand-coded” vs application generator (“appgen”)			
    
  2. Flexible data types			
    
  3. Report formatter and report control types			
    
  4. Debugger vs Debugview++			
    
  5. OCX use			
    
  6. Property syntax

  7. Conditional omit / compile

  8. Logical expression short circuiting

  9. DLLs

  10. APIs (calling into dlls)

  11. Working with VSCode / Sublime text

  12. References

  13. nuances of CHOOSE

  14. Special notations in String literals

  15. The RED file

  16. Builtins.clw and Win32.lib

  17. ? In column 1

  18. START and parameters (not the CLR stuff - but how they can be leveraged)

  19. Implicit variables (dont use them, sparky)

  20. Field equates / the use of std Clarion equates

  21. Use of EQUATE in general for making code understandable. See also “what MG says”

  22. Who / What / Where

What’s missing?

The real costs of technical debt, how to recognize its stifling impact on future development, and when to ditch it.

1 Like

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 :slight_smile:

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.