Home
JAQForum Ver 24.01
Log In or Join  
Active Topics
Local Time 05:11 02 Aug 2025 Privacy Policy
Jump to

Notice. New forum software under development. It's going to miss a few functions and look a bit ugly for a while, but I'm working on it full time now as the old forum was too unstable. Couple days, all good. If you notice any issues, please contact me.

Forum Index : Microcontroller and PC projects : CMM2: Guide to writing portable reusable code

     Page 2 of 3    
Author Message
Nimue

Guru

Joined: 06/08/2020
Location: United Kingdom
Posts: 420
Posted: 07:52am 14 Sep 2020
Copy link to clipboard 
Print this post

  mkopack73 said  Ok, this is still a work in progress, and in particular I need to work on the examples, but I've been starting to put this together and wanted to share and give folks a chance to comment.

It's up on Google Docs here: https://docs.google.com/document/d/1dkQcLM2FRTiNELj5P3neeFih0oN2tOOxC2jy3BBH5Po/edit?usp=sharing



A really useful document -- thank you.

Inevitable questions (sorry):

In the doc, this appears:

  mkopack73 said  In practice if you keep the first 5 characters of your variable names relatively unique from each other it will improve performance.


So this means that the interpreter pattern matches from the LHS?  -- OK it get that.

Is the performance increase measurable in some way? Off to make LOOOOOOOOOOONG_X and LOOOOOOOOOONG_Y variable names and iterate 10000000000 times and measure some times.

To be clear -- I am genuinely interested in this as I had never thought of variable name length before.

Cheers
Nim
Entropy is not what it used to be
 
matherp
Guru

Joined: 11/12/2012
Location: United Kingdom
Posts: 10315
Posted: 08:17am 14 Sep 2020
Copy link to clipboard 
Print this post

The document is slightly wrong in this respect. Ideally variable names should be unique in the first 4 characters. The name matching algorithm matches a word (4 bytes) at a time. A first pass just looks at the first 4 characters and discards non-matches. Then the code looks at the remaining 7 words as required to conclude the match. Performance differences will be minor but there
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 12:50pm 14 Sep 2020
Copy link to clipboard 
Print this post

  matherp said  The document is slightly wrong in this respect. Ideally variable names should be unique in the first 4 characters. The name matching algorithm matches a word (4 bytes) at a time. A first pass just looks at the first 4 characters and discards non-matches. Then the code looks at the remaining 7 words as required to conclude the match. Performance differences will be minor but there


Yeah I need to go back over the whole doc with the reference manual next to me to verify everything. A lot of this I wrote from memory without the manual or my CMm2 nearby (usually while sitting at a restaraunt or bar with the laptop out...)

Yeah the performance hit likely won’t be noticeable until you have hundreds of variables with similar names defined. But it is there, so doesn’t hurt to do things the smarter/faster way from the start.  However, as stated, if you are looking to maximize your code performance (after you are done writing your code) consider running it through the Transpiler tool to flatten it. You should keep and do improvements to your original source though as what the transpiler produces will be very hard to maintain...
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 12:52pm 14 Sep 2020
Copy link to clipboard 
Print this post

  panky said  @mkopack73

Nice work Mike, there have been a couple of previous attempts over the years but this is by far and away the best - keep up the great work.

A couple of corrections:-

1. Page 13 - the LOCAL statement in a sub or function should NOT have the DIM, it will error if you do. The same is also true for STATIC on page 14.

2. Page 13 - in your ToDo, the answer is yes, but I feel it should be STRONGLY discouraged as it is just plain confusing!

Watching with interest.

Doug.


Yeah I need to go back and certify all the examples. I wrote a lot of them while not at my CMm2 (usually while sitting at a restaraunt or bar while eating lunch/dinner).
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 12:57pm 14 Sep 2020
Copy link to clipboard 
Print this post

  matherp said  The document is slightly wrong in this respect. Ideally variable names should be unique in the first 4 characters. The name matching algorithm matches a word (4 bytes) at a time. A first pass just looks at the first 4 characters and discards non-matches. Then the code looks at the remaining 7 words as required to conclude the match. Performance differences will be minor but there


And yeah without your source for how it was implemented I had to take a stab of a guess... my description might not be 100% accurate to how you implemented it but I think the way I lay out an explanation gets the general issue across in an approachable way.
 
matherp
Guru

Joined: 11/12/2012
Location: United Kingdom
Posts: 10315
Posted: 01:07pm 14 Sep 2020
Copy link to clipboard 
Print this post

  Quote  Got it. Yeah if you use OPTION EXPLICIT then it won't matter what you set the DEFAULT to since you MUST declare the type when creating the variable.


This also needs tweaking. A variable without an explicit type will default even with OPTION EXPLICIT

e.g.

OPTION EXPLICIT
DIM A

This is perfectly valid and A is a float in this case
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 08:58pm 14 Sep 2020
Copy link to clipboard 
Print this post

  matherp said  
  Quote  Got it. Yeah if you use OPTION EXPLICIT then it won't matter what you set the DEFAULT to since you MUST declare the type when creating the variable.


This also needs tweaking. A variable without an explicit type will default even with OPTION EXPLICIT

e.g.

OPTION EXPLICIT
DIM A

This is perfectly valid and A is a float in this case


Gotcha... Yeah I think I was assuming DEFAULT NONE there - that combination would force you to have to specify.  Regardless, I've updated it. Thanks for the feedback.
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 09:02pm 14 Sep 2020
Copy link to clipboard 
Print this post

  panky said  @mkopack73

Nice work Mike, there have been a couple of previous attempts over the years but this is by far and away the best - keep up the great work.

A couple of corrections:-

1. Page 13 - the LOCAL statement in a sub or function should NOT have the DIM, it will error if you do. The same is also true for STATIC on page 14.

2. Page 13 - in your ToDo, the answer is yes, but I feel it should be STRONGLY discouraged as it is just plain confusing!

Watching with interest.

Doug.


Thanks for the feedback Doug... Fixed the example (I suspect the same is an issue in the STATIC example- I really need to test all those examples.

Yeah I want to do a good test of the functions... If I have a global named X and then pass in a parameter to the function as X, which does it use inside the function and what is the global X after the function ends?  Won't take much of an example to test it... I just need to sit down and do it. (And yes it's HORRIBLE form, but I want to make sure I explain the situation so people know what to expect if they do it...)
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 03:27am 15 Sep 2020
Copy link to clipboard 
Print this post

Ok, just revamped the section on parameters after learning a few little things that could be major headaches for folks...

MMBasic definitely does NOT work the way most languages do in terms of an activation stack and being able to see the variables defined in the lower stack frames. Also the fact that all parameters are passed by reference can make things confusing and cause unexpected results.

Certainly some things to be careful about for those of us who are used to more modern languages...

I also did some clean up on the various examples and tested and fixed up more of them.
 
matherp
Guru

Joined: 11/12/2012
Location: United Kingdom
Posts: 10315
Posted: 07:33am 15 Sep 2020
Copy link to clipboard 
Print this post

The description of subroutines isn't quite right. Variables in subroutines are created on the heap. The only use of the stack is by C in the recursive call of the processing engine components.

Also, I think you are overemphasising the differences between MMBasic and say C
Passing by reference in MMBasic is exactly the same as passing a pointer in C
int x=7;
myfunc(&x);

void myfunc(int *anything){
*anything=4;
}

vs

x%=7
myfunc(x%)
sub myfunc(anything as integer)
anything=4
end sub

In both cases "anything" is a locally named pointer to the incoming value. In MMBasic whether you name the function parameter x% or anthing makes no difference exactly like C
Edited 2020-09-15 18:56 by matherp
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 12:44pm 15 Sep 2020
Copy link to clipboard 
Print this post

  matherp said  The description of subroutines isn't quite right. Variables in subroutines are created on the heap. The only use of the stack is by C in the recursive call of the processing engine components.

Also, I think you are overemphasising the differences between MMBasic and say C
Passing by reference in MMBasic is exactly the same as passing a pointer in C
int x=7;
myfunc(&x);

void myfunc(int *anything){
*anything=4;
}

vs

x%=7
myfunc(x%)
sub myfunc(anything as integer)
anything=4
end sub

In both cases "anything" is a locally named pointer to the incoming value. In MMBasic whether you name the function parameter x% or anthing makes no difference exactly like C


I wrote it that way figuring that C-like languages tend to be the dominant versions in use today and thus are likely what most people will be familiar with (PBV by default), where as MMBasic is doing a Pass-by-reference (like you said, the pointer). Yeah, I need to expand that section (just written last night) with some diagrams to visualize what's happening in memory to make it more clear to people that the address of where the value is in memory is what is passed to the function to create the parameter, not the value itself. Thus you are still working with the same actual data point and if you modify it, you're modifying it everywhere, not just in a copy that only exists inside the function itself. I think that is important to note as it will trip people up - change the name of the parameter variable all you want, you're still really working with the original variable for all intents and purposes...
 
Mixtel90

Guru

Joined: 05/10/2019
Location: United Kingdom
Posts: 7937
Posted: 07:55pm 15 Sep 2020
Copy link to clipboard 
Print this post

Is it important to go into such detail about how variables work?
MMBasic only has Global and Local variable types.

As far as the user is concerned all variables are global unless specified as Local within a Sub or Function, in which case no changes are made to a global variable of the same name.

BASIC isn't C and it doesn't seem sensible to confuse how the two work.
Mick

Zilog Inside! nascom.info for Nascom & Gemini
Preliminary MMBasic docs & my PCB designs
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 09:37pm 15 Sep 2020
Copy link to clipboard 
Print this post

  Mixtel90 said  Is it important to go into such detail about how variables work?
MMBasic only has Global and Local variable types.

As far as the user is concerned all variables are global unless specified as Local within a Sub or Function, in which case no changes are made to a global variable of the same name.

BASIC isn't C and it doesn't seem sensible to confuse how the two work.


I just figure it's useful for those of us who come from other languages to have it clearly indicated how things work, as it's very different than we might be used to. What might be super clear to you might not be to somebody else especially if they come from languages like C for a long time.

Additionally I find it's useful to explain the HOW and WHY not just "Do it this way" so people understand the reasoning for what they're experiencing. The best programming books give you some insight into what's happening in the machine when you do something - it lifts the veil of mystery and brings clarity.
Edited 2020-09-16 07:59 by mkopack73
 
PeteCotton

Guru

Joined: 13/08/2020
Location: Canada
Posts: 543
Posted: 08:48pm 16 Sep 2020
Copy link to clipboard 
Print this post

  mkopack73 said  
I just figure it's useful for those of us who come from other languages to have it clearly indicated how things work, as it's very different than we might be used to. What might be super clear to you might not be to somebody else especially if they come from languages like C for a long time.

Additionally I find it's useful to explain the HOW and WHY not just "Do it this way" so people understand the reasoning for what they're experiencing. The best programming books give you some insight into what's happening in the machine when you do something - it lifts the veil of mystery and brings clarity.


It sounds like you have two target audiences. New programmers and people coming from other languages. Might I suggest that the main body of the text is the overview for new programmers, and then you have a breakout box marked for more advanced programmers, that is easily skipped over by someone just learning.

That way it doesn't become overwhelming for newcomers and they will pick up some good practices (rather than reading all of the text and quickly feeling bogged down and out of their depth). And then when they are comfortable with the general ideas they can dive deeper in to each subject.
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 02:40am 17 Sep 2020
Copy link to clipboard 
Print this post

  PeteCotton said  
  mkopack73 said  
I just figure it's useful for those of us who come from other languages to have it clearly indicated how things work, as it's very different than we might be used to. What might be super clear to you might not be to somebody else especially if they come from languages like C for a long time.

Additionally I find it's useful to explain the HOW and WHY not just "Do it this way" so people understand the reasoning for what they're experiencing. The best programming books give you some insight into what's happening in the machine when you do something - it lifts the veil of mystery and brings clarity.


It sounds like you have two target audiences. New programmers and people coming from other languages. Might I suggest that the main body of the text is the overview for new programmers, and then you have a breakout box marked for more advanced programmers, that is easily skipped over by someone just learning.

That way it doesn't become overwhelming for newcomers and they will pick up some good practices (rather than reading all of the text and quickly feeling bogged down and out of their depth). And then when they are comfortable with the general ideas they can dive deeper in to each subject.


It's a tough situation - My intent is not to be an all emcompassing "Here's how to do everything in BASIC" for beginners - there's tons of those sorts of books out there that will cover it much better than I could. At the same time, there are things that beginners looking to go to the next level need to know, or at least should have explained to help them not only learn what to do but also why it works (hence the deeper explanation of PBV vs PBR).  In fact one of the biggest things I found frustrating when I was doing Java back in the early 2000's was that there were books that were for beginners that were great, but then the next series of books were meant for experts - there was nothing that really helped bridge the gap between the two.  I ended up helping out writing and tech editing a book meant to do just that, help bridge the gap and get people across that hump (Java 2 Unleashed).

For the more advanced person who knows lots of different languages, I'm trying to point out little gotchas or quirky things about MMBasic on the CMM2. Things that yes are mentioned in the manual, but could easily be missed (I know there were several I missed in my first couple readings or at least didn't sink in until I tried some tests and that's when I got it.)

At this point I'm mostly just trying to get all the information down. Can always restructure the presentation of it later... Heck, pretty much every time I sit down to write more I figure something else out that I hadn't thought of that might be useful to somebody.
Edited 2020-09-17 12:51 by mkopack73
 
Turbo46

Guru

Joined: 24/12/2017
Location: Australia
Posts: 1642
Posted: 04:40am 17 Sep 2020
Copy link to clipboard 
Print this post

  mkopack73 said  MMBasic allows you to choose between arrays that have their initial index at 0 (C/C++/Java style) and arrays where the first index is a 1 (old school BASIC style). You choose this by using OPTION MODE 0 (or 1).

Actually, in my experience with several versions of BASIC - OPTION MODE 0 was always the default and OPTION MODE 1 was not always available.

Sorry. but in my opinion you have overdone the explanation of arrays to the point of making it a bit confusing. My simple approach is to never use OPTION BASE 1 but be aware that 0 is the first element and either use it or ignore it. If you want to populate an array when you dimension it do something like:

Dim String days(7) LENGTH 3 = ("","Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat")

where Sunday is day 1 or:

Dim String days(6) LENGTH 3 = ("Sun", "Mon", "Tue", "Wed", "Thur", "Fri", "Sat")

where Sunday is day 0

You could then describe how the LENGTH directive can save memory and then go on to describe 2 and 3 dimensioned arrays and give an example of their use. I think new users struggle more with that concept than single dimensioned arrays. Also whether you fill an array when you Dimension it or fill it using a FOR-NEXT loop reading DATA statements, the program contains two copies of the data and if space is a consideration then load the data from a separate file.

I agree with your assertion that MMBasic contains a "certain degree of over-flexibility" and think the recent additions of OPTION ANGLE and OPTION Y-AXIS are examples of that.

Bill
Keep safe. Live long and prosper.
 
matherp
Guru

Joined: 11/12/2012
Location: United Kingdom
Posts: 10315
Posted: 07:17am 17 Sep 2020
Copy link to clipboard 
Print this post

  Quote  I agree with your assertion that MMBasic contains a "certain degree of over-flexibility" and think the recent additions of OPTION ANGLE and OPTION Y-AXIS are examples of that.


Lets be clear these were added because a teacher using the CMM2 in the classroom requested them in order to help with students who haven't yet encountered things like radians.

Given a choice between supporting something like this and difficulties for an intellectual exercise in re-use of code then there is no decision to make.
 
Nimue

Guru

Joined: 06/08/2020
Location: United Kingdom
Posts: 420
Posted: 08:11am 17 Sep 2020
Copy link to clipboard 
Print this post

  matherp said  
  Quote  I agree with your assertion that MMBasic contains a "certain degree of over-flexibility" and think the recent additions of OPTION ANGLE and OPTION Y-AXIS are examples of that.


Lets be clear these were added because a teacher using the CMM2 in the classroom requested them in order to help with students who haven't yet encountered things like radians.

Given a choice between supporting something like this and difficulties for an intellectual exercise in re-use of code then there is no decision to make.


I know that I'm a "newbie" to this scene and the forum - but can I bring some perspective here (imagine full on teacher mode - so sorry upfront).  Pull up a chair....

As a 48yo educator (based in the UK - sort of relevant) I've seen just about every "computer" / "ICT" trend come and go in education.  But the sad truth is that over the years, the skill set of both the teachers and students has declined. Period.  To the point where making a cat bounce up and down (Scratch for the uninitiated) is seen as the peak of "good practise" in primary / lower secondary school.  

But during that same time scale, computers have become ubiquitous.  And in many ways, that is the problem.  We have generations of people who can use the interface of programs based on a GUI, often to create some excellent stuff - (Fusion 360 and Blender in school is a joy to see).  But the link between the user and the "computer" has become far too far for most to relate their actions to the device they are controlling.  Just like the magic that is my hybrid three cylinder engine -- I can use the car, but have no idea how it works.  30 years ago, I knew about "suck, squash, bang, blow" and could explain how an internal combustion engine worked.

Over the years, I have tried to integrate more "hands on tech" into the classroom - data loggers, Bee Bots (an abomination), PIs, Arduinos and MicroBits  >> but all have been an extension of the computer and as such are subsumed into the relationship between the user / PC.  As I said above, people have become "users" of this stuff.

When I saw the CMM2 on Atomic Shrimp (and then 8-bit Guy) -- I had a literally "OMG" moment and went and gave my money to WhiteWizzard. I had that visceral feeling like I did when I was given my ZX81  and no, I'm not being a nostalgia nerd.

That feeling was comprised of equal measures of; potential, expectation and the intellectual thought that I could understand the "whole thing".  This was something that I had to bring to the education scene.

The device arrived - and within 30 minutes I had coded (using a language I had not touched for 30 years) a light sensor that display intensity on the screen - that I calibrated to Lux.  Never using Arduino, Pi or Microbit have I achieved so much, in so little time.

I have used my CMM2 in front of children from 6 to 18 -- and every single time the response is similar to mine, often more.

So now, instead of making a Cat bounce up and down for the sake of it -- I have a class of 9yoo who have just written some .INC files.  These .INC files have some "maths" and "graphics" -- is a number prime? Sum from x to z, draw a bar chart, draw a pie chart etc etc.   They managed this within 2 x 1hr sessions.

My point in this rambling post:

(1) The CMM2 is not a "niche" product - it offers so much, to so many that it is applicable to all sorts of use cases.  As such it is a practical project, not an intellectual one  (no offense intended to anyone)
(2) It's "Pick up and go-ness" needs to be protected at all cost >> literally the killer USP for my use case
(3) All languages / hardware have their nuances / foibles and we just work around them -- that problem solving element is actually a useful learning point (my case entirely with the coordinate system)
(4) The open hardware and more "closed" software ecosystem works for me.  I'd rather back a project that is driven by a small core team (with values, direction and drive) than a fully open source gig -- in my world, a horse designed by committee usually ends up looking like a camel.

The responsiveness of the team, the advice and guidance offered by this community and the joy (and I mean that) of using the CMM2 surely means that we can all pull together.

Nim
Entropy is not what it used to be
 
thwill

Guru

Joined: 16/09/2019
Location: United Kingdom
Posts: 4311
Posted: 09:24am 17 Sep 2020
Copy link to clipboard 
Print this post

  Nimue said   ...


+2

Tom
MMBasic for Linux, Game*Mite, CMM2 Welcome Tape, Creaky old text adventures
 
mkopack73
Senior Member

Joined: 03/07/2020
Location: United States
Posts: 261
Posted: 12:08pm 17 Sep 2020
Copy link to clipboard 
Print this post

Turbo - sorry but my experience is as I described. - BASIC on the Vax, Commodore line of 8-bits, IIRC Atari 8-bit BASIC, and IIRC MS Quick Basic all were 1 indexed (might be wrong with qbasic, I only used it briefly for 1 summer). It was the biggest thing I had to unlearn when I moved to C in 1991. Hadn’t touched BASIC since but I distinctly remember it. If you came from other platforms, you might have had different experiences. There had to be SOME machines that were 1-index based or Peter wouldn’t have bothered to put the OPTION in. It all just depends on where you came from in your computing history.

Case in point, at work we had a piece of fairly complex large software in Java (I didn’t work on it or I NEVER would have allowed this) that one of our PhDs (I don’t know what it is in) largely wrote the initial version of. I don’t know what language she had come from but it was a 1-based index system and she didn’t understand that Java did arrays 0-based so she added 1 to every index when interacting with the arrays.  OMG what a nightmare when a few years later we tried to make some updates/additions to that code to use it on another project! It ended up so bad that we had one of our Java experts completely rewrite the whole thing from scratch...

Regardless, just ignoring the 0’th item in the array is HORRIBLY bad form and can bite you in the ass with unintended consequence if you aren’t careful. It also makes your code less understandable to others (“why isn’t he using the 0th item? Is that intentional or a mistake?“). You really shouldn’t ever do that.
 
     Page 2 of 3    
Print this page
The Back Shed's forum code is written, and hosted, in Australia.
© JAQ Software 2025