Skip to Content
Personal Insights

Sorry. I promise to code my tutorials better

Don’t you hate when someone writes a tutorial showing you how to do something — in a way no one in the real world would ever do?

  • No error handling
  • Just Hello World and nothing more
  • Using brute force
  • Half-completed tasks
  • Simple and obvious features (that everyone would use) not used

Well, while testing my tutorial to see if it works on the new Free-Tier services (see this blog by Riley Rainey), I suddenly realized how much better I could have written the tutorial. And I noticed it because the API I was calling failed, and therefore my entire webhook failed. 🤦‍♂️

Webhook for SAP Conversational AI

I had written a tutorial to show how to write a Python webhook that could be called from SAP Conversational AI. It’s probably the tutorial I’m most proud of, since I had to learn SAP Conversational AI, then Python, then Flask, then BTP, then CF, then CF CLI, then a few more things.

But during testing to see if it works on BTP Free-Tier, I saw a few things I should have done better.

  • The first thing I noticed was that I had to enable CF for the whole thing to work. Not terrible, most people would figure it out, but still.

  • During the CF CLI process, I told people to select their subaccount. But on the system I was now using, I had only one subaccount, so it was automatically chosen for me.
  • Still during the CF CLI upload process, I got an error because I had enabled CF but did not create a space.
  • And finally during the CF CLI upload process, I got an error because the version of Python I had specified for the app was from a “long time ago” – 3.8.5. Why I did not long ago specify 3.x, I don’t know.

  • Now for the webhook code. The API service I was calling failed, which crashed my webhook. so the first thing I did was to redo my code. It had been like the following – no error handling, no worries if the API was down:
    url = "https://cat-fact.herokuapp.com/facts/random?animal_type=" + animal + "&amount=1"
    
    r = requests.get(url)
    fact_data = json.loads(r.content)
    
    

    Now I changed the code to still work if things went bad:

    url = "https://cat-fact.herokuapp.com/facts/random?animal_type=" + animal + "&amount=1"
    nodata = {"text" : "No data"}
      
    try:
        r = requests.get(url, timeout=5)
        fact_data = json.loads(r.content)
    except:
        fact_data = nodata
    
    • I added the nodata variable to hold dummy text so I could return something no matter what, and so my webhook would continue to work.
    • I put the web call in try/except block, to capture when the call failed (like now).
    • I put a timeout for the web call because, even though I now caught the error, my webhook was hanging and taking a long time to return.
    • I added code to set my data to the nodata variable, in the case of an exception.

They say you learn the most when you struggle, make mistakes, tinker. I felt powerful, finding a better way to code, not just the fastest way. These were small victories, but I felt I was gaining some real understanding.

Of course, I’m sure you can find other things to improve the tutorial. If you do, feel free to open a GitHub issue or comment on this blog.

Better Tutorials

I will redouble my efforts to have tutorials reflect more real-world situations, without making it so complicated that you can’t learn the basics of what you came to learn in the first place.

See all our fabulous tutorials in the SAP Tutorial Navigator.

2 Comments
You must be Logged on to comment or reply to a post.
  • Nope - Unforgivable.  There is nothing to forgive.

    You took the time out to write the tutorial, and then revisit it later.   That is amazing.   I for one am applauding you this morning.  Thank you for taking the time to look at it a second, third or one millionth time.

    Here's the thing, some tutorials are not very good.  But if I take the time to muddle through them, I find I have a better understanding than if I was given the complete solution.  But that's just me.  Sometimes I need something really quick.  When that happens, I usually don't look towards tutorials.  Those are for the times when I want to really learn something.

    Some people will disagree with me. I've been told that we don't really want someone to learn something the wrong way.   I can understand that.  But if they don't begin to learn - it doesn't matter.  I remember my first ABAP course.  (And yes, it was from SAP)   We learned how to use logical databases.  We also learned select *  - and no into table it was select * do some programming / endselect.  Within the first few weeks, I found out what a mistake that was.   The runtime was horrible, debug would break....  and...   I still remember it.

    But if I think about the development I've done/am doing.  There is always something I could do better.  Keeping the tutorials up to date is going to be quite a chore.  We are in a place where the technology is coming at us really fast.  Things are changing, and if you don't take tutorials, books, and well any learning sometimes I question them all.  Eventually coming up with my own style.

    So thank you - and I'm 100% sure your tutorials will get better.   I, myself struggle a bit thinking about doing a technical blog.  Why?  Because I'm 100% it won't be "right" as in I didn't follow all the clean code directive.   <Smile>  Or I will just confuse someone.

    And as usual - I'm very verbose.  I hope everyone visits the tutorials as time permits.  They are well worth it.

  • Thanks, Michelle Crapo for your comment (almost as long as the blog) and for applauding. I agree that when I need something real quick, I basically end up on stackoverflow looking at the accepted answer to a relevant question (as I just did to understand Dockerfiles or jq or httpie as I was trying to learn GitHub actions).