Guidelines

As you start to code all day, every day, you start to develop your own set of guidelines.  I’d call them rules, but since I break them often enough I have to call them guidelines.  Since I deal with my own code and Other Peoples Code (OPC) on a regular basis here are my guidelines (in no particular order):

  • Name any control you reference in code.  It needs to make sense to you.  If you have a bunch of Pushbutton1, Pushbutton2, etc. pushbuttons you are causing yourself grief in the long run.  You’re coding not only for right now, but for 5 years from now when you’re not intimately familiar with your UI and you want to make a change or fix a bug (or hand it off to a consultant).
  • If you find yourself copy/pasting code over and over again you should think about a global method or perhaps a subclass.  I’m talking about the MessageDialog alerts, the ComboBox helper code, etc.  The reason this is a problem is that if you have the same code all over the place and you have to change it, you then have to change it everywhere.  The chances of missing one hase big bug implications and your clients/customers may not appreciate the bug.  This is called, by the way, refactoring and it’s not a bad thing to do.
  • Big, huge, monolithic methods/functions are not good.  My general rule is that if my method is over a screen length I start looking at ways to break it up into smaller chunks.  This makes it easier to debug too since the runtime exception doesn’t have line numbers on where a bug occurred.  All it can give you is what the error is and where it occurred (and even sometimes that’s not reliable).
  • Name your variables something that make sense to you.  You need to come up with your own guidelines, but the reason is the same as naming your controls.  You should, at a glance have some level of understanding of what the variable is for.  I don’t name loop variables (i, j, k, x, y, etc) unless I have nested loops.  Some would argue that prefixing your variables is a dumb idea because RB is very strongly typecast and if you change the type you then have to change the prefix.  Um…sure…that’s what global search and replace is for.  But I can tell at a glance what type the variable is.
  • Name your methods/functions something that make sense.  Same reasons as above.  If you can’t figure it out at a glance what it does, then you might need to rename it.
  • One that keeps haunting me (in other words I haven’t always learned the lesson on this) is to use a thread whenever there’s a tight code loop.  It always seems that during testing I have far less data than I will in real life so that tight loop that only takes a blink during development takes seconds in production and causes the app to ‘freeze’.  Threads are a natural way to solve that problem.  I urge you to not use refresh statements in your loops – instead use a thread.  Of course threads aren’t perfect in that you then have to worry about how you update UI but if you have the Thread in the window you’re generally pretty safe.
  • Test your cross-platform apps on each platform.  Don’t assume that your Mac OS X application created in RB will look good on Windows and vice versa.  Trust me on this one.  Depending upon what you’re doing, Windows can be hugely different performance-wise than the Mac and Linux.  Double-buffering is standard on Mac OS X and Linux but NOT on Windows so that really great looking custom control on Mac/Linux looks just awful on Windows because of flickering.
  • Project organization is important.  As your project gets bigger and more complicated having the big monolithic list of objects becomes harder to find things.  I generally start with Application, BKS, Others, and Assets folders in my projects and put everything in those folders.  The assets folder is icons and any other graphics for the projects.  The application folder has all app object, all the windows and application specific objects.  The BKS folder contains my own toolset of classes, subclasses, extensions, etc that I’ve written and use in most projects (I generally try to retain rights to any code in this folder).  In the others folder is my toolset of objects that are from others and I don’t claim that I wrote.  Some of these are encrypted and others are not.  Keeping your project tidy is a good thing.
  • Code first for functionality and once it’s working you can test for efficiency.  I’ve found that some things I thought would be slow weren’t and some things I thought would be ok weren’t.  Get it working first and THEN worry about it.

Those are mine off the top of my head.  What guidelines would you share with someone new to coding and/or REALbasic?

9 thoughts on “Guidelines

  1. The main things I would add.

    Never use abbreviations. Writing exactly what it is which makes it easy to read many years down the track.

    For example which is clearer.

    cbo versus checkBox
    tbo or txt versus textBox
    nValue versus valueInteger or valueFloat

    Abbreviations do not scale well. As you use more languages you need more abbreviations.

    If you want explain the type in the name of the object use a suffix instead of using a prefix.

    For example

    maintenanceCollection instead of CollectionMaintenance.
    nameTextBox instead of tboName
    salutationCheckBox instead of cboSaluation.

    Cheers

    Keith

  2. Well, I’d say it depends upon what your standards are. A checkbox named cbSomeName is good enough as long as you *always* use cb for checkboxes. The key, though, is to be consistent! I highly recommend creating a standards document.

  3. Hi Bob

    That’s what I mean.

    Write cbSomeName and reference a standards document for clarification versus
    writing someNameCheckbox which is clarified as you read with the explicit context of the language that you are using … what does cbSomeName mean in FoxPro, or Visual Basic, or .net, or java, or php or c++ or objective C or …

    An example – someone wrote some code for me where they called the first database , database1, the second one, database2. Lets say they used a prefix and a meaningful name. Say sdbMaintenance and sdbBalanced. I then refer to the standards documents to work out that sdb stands for SQLite Database … versus maintenanceSQLite or maintenanceDatabase and balancedDatabase or balancedSQLite.

    Using explicitly named objects with the type as a suffix is much easier to read, _for anyone_, versus having to refer to a standards document as you read.

    Cheers

    Keith

  4. Defensive coding : Ensuring your users can only enter valid data is imho awlyas wrtoh the erffot.
    Bad data in the database makes a bug fix a much bigger deal

  5. The same with spelling … I often post posts with incorrect spelling 🙂
    I wish I had a defensive spell checking that always kicked in before I posted 🙂

    Cheers

    Keith

  6. @jjb Yeah, that’s a good one. Validating user data to ensure that it’s good will help eliminate problems in the long run.

    Another one that I’m starting to use more often is to use Assertions validating parameters. If I expect an object to be non-nil I check for that. If I expect an integer to be > 0 I check for it and so on. Defensive coding takes a little bit more time at the beginning but it can often save you from a lot of work later on.

  7. I might describe the use of assertions as offensive programming. As Bertrand Meyer has written, one should distinguish between the program attributes of correctness and robustness. Defensive programming is about making programs robust; that is to say, that they handle external input. Assertions are used to verify correctness. For example, one can use preconditions and postconditions to allocate responsibility, to make explicit that a function argument should be > 0, or to ensure that a sort routine actually returns a sorted array.

Comments are closed.