How to make Clarion development suck less
Skip to end of metadata
Go to start of metadata
by David Harms

I've been to a ton of conferences and heard a lot of keynote speeches, and I don't remember many of them. Nick Petreley's Clarion keynote of many years is one I do recall, but mainly because of the cool Pinky and the Brain clip he showed and not because of what he actually said. And Hank Asher's Clarion keynote has stuck with me because a few years later I was contacted by a lawyer interested in my recording of that event. 

But at the Open Source Convention (OSCON) in 2006 I heard Six Apart's Anil Dash present Trying to Suck Less: Making Web 2.0 Mean Something. I was floored. It wasn't so much his take on web development, as good as it was. It was the frank admission that what we do as software developers so often sucks. That's just the nature of the beast, and it's okay as long as we continually try to suck less.

I came away with a whole new perspective on my work as a software developer. I've written code that I'm proud of, and code that should never have seen the light of day. Some of my best code from years ago really really really sucks. But it was the best code I knew how to write then. 

The real question is, how do I improve my code right now, using the best practices that are available? 

There's a whole lot room for improvement in the Clarion world. Yes, we have a great tool that can <insert your favorite rant about Clarion's magnificence here> better than anything on the planet.

Big deal. Your customers either don't or shouldn't care about what tool you use. They care that you can deliver reliable code that does what they need it to do, at a price they can afford. Similarly you care (or should care) that you can create the required functionality with the highest reliability and the lowest total cost. 

Clarion's application framework and code generation technology provide a huge assist; you get rapid production of highly reliable code, easily maintained and extended within the AppGen environment. But what happens when you want your app to do something the AppGen and its many templates can't handle? 

That's when you start writing your own code. And that's when you really start taking responsibility for the quality of your own applications. 

A lot (though not all) of what we can do to suck less involves writing better code. 

The purpose of this page

Every page needs a purpose, and this one is to provide the current state of my thinking about the best possible way to do Clarion development. It's a work in progress, and these are early, early days. Look for many more links and articles in the months ahead as well as new page content.  

A lot of the content that will be linked from this page is for subscribers, but you will find links to external sites as well. And if you have something to say or share, please post a comment!

If the subscriber-only links below are inactive then you're either not logged in or you do not have an active subscription. For more information on subscriptions click here.

Sucking less

Here are some of my favorite ways to make Clarion development suck less:

THE BIG ONE: Get that business logic out of embed points!

Embed points are like crack, and way too many Clarion developers are embed-heads. It's just so easy once that embed point is open to keep on writing. Stop! NOW!! Code in embeds is typically non-reusable, awkward to test, difficult to maintain, and frequently unreadable due to excessive length. You need to put that code somewhere you can test it and reuse it.

(tick) Subscriber content: The Problem with Embeds, Revisited

To some degree you can accomplish this by moving the code to source procedures, but classes are generally a better solution. Which leads to...

Learn object-oriented programming

I know, you don't have to know OOP to code in Clarion (even if ABC apps rely heavily on classes). But there's a reason object oriented programming is ubiquitous. It. Just. Works. And it can make so many things about development much better. Yeah, I know, the next better thing is always around the corner. Aspect-oriented programming. Functional programming (again). But OOP is still the best way I know to model most business logic. Get with the times. 

Take a layered approach

Start thinking about your apps as having distinct areas of code responsibility: user interface, business logic, database access, and the database storage (there are other ways to break this down, but this is a common approach). Although Clarion procedures tend to combine all the layers in a single procedure, you can still adopt this kind of separation when dealing with your own code. 

Move to SQL (if you haven't already)

There are lots of SQL flavors out there, and almost certainly you can find one that is a good replacement for your current flat file database. Once you go SQL you never want to go back. 

(tick) Subscriber content: Our massive 600+ page ebook on databases & SQL

Make your code readable

Use fully descriptive names for variables, procedures, classes, methods etc. Keep individual code blocks (procedures, methods, routines) short and focused on one task. If you find yourself needing to comment your code then it's probably too obtuse; code should be its own description. Adopt a naming convention (but please, not some variation on systems Hungarian...).

Take an API approach

The golden age of the standalone desktop app running on just one platform is coming to an end. That doesn't mean the end for Clarion, but it does mean that Clarion's role is beginning to change. A system might have a desktop component, a web component, a mobile component and any number of services. Think about how you can extract functionality from your code base. Perhaps you have code that a mobile app might need to call, using JSON as the data format. Or there's a web app somewhere that needs to call your code via a web service. 

Break long processes down into Hanson Loops

What's a Hanson Loop? It's a construct Mike Hanson once provided for me in a procedure I wrote, and which I liked so much I've used it many times since. Plus I think the name Hanson Loop sounds cool. It's also a great example of the benefits of turning routines into local procedures. 

(tick) Subscriber content: Clean up your code with the Hanson Loop

Exchange your routines for local procedures
Guess what? This is another technique you can learn about in the Hanson Loop article. 
Use bug tracking software

I've used FogBugz in the past; I'm currently a huge fan of Atlassian's Jira which is tremendously powerful yet very easy to use. You have a world of choices; find a bug tracking system that fits your needs and use it. This is especially important in a team development environment. 

Create unit tests for your business logic

Use ClarionTest or CWUnit to unit test your business logic, or set up your own testing framework/coding convention. As much as possible, be able to test your business logic apart from the user interface or the database. This will make development, maintenance and even design easier. Once your business logic is right you can write it into the UI and/or the database. And now that I have you thinking about unit tests...

(tick) Subscriber content: Many-to-many checkboxes revisited

Adopt Test-Driven Development

Whether or not you use one of the existing Clarion unit testing frameworks, you can still adopt the Test-Driven Development approach. TDD has numerous benefits not just for code reuse and reliability, but also for code design. I can confidently say that TDD has done more for the overall reliability and maintainability of my applications than any other practice I've tried. It's also had a significant positive effect on the way I structure my code.

Create integration tests

Unit tests run standalone and are typically lightning-fast and run constantly during the development phase; integration tests use databases and other external resources. Because of these external dependencies they typically run more slowly and are more fragile, but they can also be a vital part of your development toolkit. 

Use version control

Keep your Clarion environment and your applications under version control. I like Git, but what you use isn't as important as that you use it. Version control is also a critical component of just about any build server. 

Create a build server

Once you have your code under version control you're not that far away from creating a build server that sees when you've committed code to the repository, pulls that code and does an automated build. Especially useful in large multi-app systems with multiple developers. 

Automate your tests

Ideally your tests should run as part of your automated build process, but the tooling for this isn't readily available yet. Watch this space for further developments.

Align procedure and method return values with ABC

It took me years to get comfortable with ABC's standard for return values, but I'm fully on board now. It was the above mentioned Hanson Loop that finally pushed me into the Level: zone.

What else?

How about you? What are your guiding principles for Clarion development? Post a comment below!

 

 

Labels
  • No labels
  1. Great article David!

    We are struggling to achieve at least some of the goals you listed here.

    We've just completed the transition of our code under a version control system (Git with the aid of Upper Park version control interface) and I'm writing some hook scripts that should help us not loosing code in the case a programmer forget to save .apv files and commit them to Git.

    But right now I'm interested in the creation of a build server and I don't recall that I ever read anything about this topic.  Any idea about which tool to use to set up a build server.

  2. I agree completely about keeping your code readable... it should read like a book (That's what my Cobol Professor told me). However, I think comments should be used for clarification.. sometimes I'll write a comment that explains the concept of what I'm doing, especially when it's complicated. Sometimes you do have to write complex code. However if you create variable and routine or procedure names that make sense, your comments will be less.

    I'd give you some examples but I'm reading your 'Problem with Embeds' article.

    Good article.

    1. I agree.  well written code can tell you whats going on, but not Why it's happening.