Mintoris Forum

Author Topic: Guidelines for include file var & sub naming  (Read 4455 times)

Jesse

  • Sr. Member
  • ****
  • Posts: 126
  • If life throws a planet at you, pull your ripcord‼
Guidelines for include file var & sub naming
« on: Mar 15, 2011, 07:19 PM »
With the addition of include files to Mintoris Basic come many new wonderful and exciting  prospects. We are now able to break large projects into smaller functional, and reusable, code files. And we are now free to use additional functionality without having to write the extra code, much like using libraries.

It is this area i wish to address. Since the include files will be written by different people than those using them, there should be some guidelines in place to reduce, or hopefully eliminate, variable and sub naming conflicts, sinc as if this writing, Mintoris Basic has no provisions for allowing private namespaces, so ALL global variables and ALL sub names share the same namespace, so duplications are not allowed.

These guidelines are suggestions only. It is not mandatory to use them. But… Using them will make life easier for all involved, including yourself.

1) Use global variables sparingly. This goes especially for those writing include files. Instead of global variables, consider passing info back and forth to your helper routines using arguments. Use global variables only when there is no other way to get it done. This cannot be stressed enough. The fewer global variables, the less chance of conflicts.

2) If you must use global variables, their name should be descriptive and meaningful. This goes for sub naming as well, because they are global too. Declaring short, simple variables as global is inviting disaster to your code, and possibly the code of others as well. The intent is to reduce the likelihood of having a global and local variable using the same name. As far as sub names go, this will reduce the likelihood of a sub in the main code body having the same name as a sub in the included code file.

3) Include file global variable and sub naming: A suggestion would be a 2-3 character author identifier, followed by a short, meaningful, discriptive name that identifies the purpose or intent of the include file, followed by a short discriptive name that identifies the purpose of the individual global variable or sub. I use this strategy when naming any element that's publicly exposed in the globally. An example: I wrote an include file called wsRC4.bas, to give the user encryption capabilities in their code. My author identifier is 'ws' which identifies my software company WarSOFT Apps. The name of the purpose is 'RC4'. It has two subs, wsRC4CreateKey$() and wsRC4Encrypt$(). See how using this naming technique dramatically reduces the likelihood of accidentally using the same sub name in two places? Also remember that since there is no provision for private subs, even your helper subs that would normally be declared as private should be named in this way as well, because they too are public. The wsRC4 library uses no global variables, but if it did, they would use the same technique. If a global variable just had to be used, to store the generated key for example, it'd be named wsRC4Key$.

4) Keep local and non-global, general purpose variable names short and simple. They can be discriptive if need be, but should be kept as short as possible. This will help prevent duplicate name conflicts between the global and local namespaces.

Thank you for bearing with me. Remember these suggestions are just that. Suggestions‥ If any other techniques help in this situation,  please post them here. Also please feel free to discuss these here.

Jesse

barryem

  • Full Member
  • ***
  • Posts: 17
Re: Guidelines for include file var & sub naming
« Reply #1 on: Jul 18, 2012, 05:27 PM »
I'm sure I'm not the first one to think of this but one way to deal with global variables is to do them in upper case and make local variables lower case.  I just started with MBasic yesterday but as soon as I read that it was case sensitive I decided to do that.

I began programming in the days when all variables were global and I had to learn better habits in later years but now that I'm only writing very small programs for fun I can have all the bad habits I want and I like using a few global variables.  I even enjoy using (shudder) GOTO. :)

Barry

mjcoon

  • Sr. Member
  • ****
  • Posts: 116
Re: Guidelines for include file var & sub naming
« Reply #2 on: Jul 21, 2013, 12:18 PM »
….  I even enjoy using (shudder) GOTO. :)

Barry


I think that smacks of the indulgence of second childhood/novicehood. Despite that, if I GOTOed, I would not really enjoy it; too brainwashed, I think‼  :)

barryem

  • Full Member
  • ***
  • Posts: 17
Re: Guidelines for include file var & sub naming
« Reply #3 on: Apr 22, 2014, 09:25 PM »
I guess you have to consider my beginnings as a programmer.  I started in the mid to late 1960's programming mainframes that were capable of running up to 5 jobs at once…in theory.  In fact they slowed to a crawl with more than 2 jobs running unless those 2 jobs were extremely efficient.  Then you might manage 3 jobs.  These were expensive large computers with more work to do than there were hours in a day to do so efficiency was everything.

We not only weren't encouraged to write readable code, we would have eventually been fired for it.  Things were done with maximum CPU and memory efficiency.  Nothing else mattered.  There was no concern for maintenance issues or for how long it took to code and test.   It had to work and be efficient and that was everything.

Back in the days before 2000 when there was so much written about why we had the Y2k problem reporters and columnists loved to say that we just weren't thinking.  They were wrong.  We saw the potential.  We discussed it at length.  We made the only choice possible.  We ignored it and left it for future decades to deal with.

By the way, GOTO wasn't considered a problem in those days.  It was everyday stuff.  COBOL had it's perform statement and it was used a lot where it made the most sense.  It saved memory.  And GOTO was used, always to create the spaghetti code that got our pay raised. :)

Self modifying code was fairly standard, as well.

For what it's worth, these were techniques we were taught in school.

Also, it's worth remembering that the computers in those days didn't have a return stack.  That made a huge difference in the way we coded.

In later years I had to learn proper new age coding.  It was never as much fun but it became important to make code readable and modifiable, especially by less experienced programmers.  I have no issue with that.  It was a new world and we had to live in it.  But it sure wasn't as much fun. :)

Barry