Coding notes

EEA index

FileStore
Description
Hardware
Error codes
NVRAM
Disc format
Disc image
Accessing
Password file
E01 vs E01S
Rescuing
Emulator

Executable
Source
EPROMs
Mem. map
Licence
Versions
Modules
SD card

Intro
MDFS
Others
Clocks
Bridges
Interfaces
Misc h/w
Testing
Misc info

The design philosophy is for simple legible code.
While speed tweaks and clever code is usually something to be desired in an emulator, this holds little value if you are the only one that can understand your code.
If you have a choice, choose to write code that is obvious and largely self-documenting, instead of something that relies upon tricks, side effects, or just plain ordinary Deep Magic.

The 'rules' below are to aid in consistency so additions to this project blend in with the rest of it.

  • Indents are 2 SPACE characters. Strictly no tabs.
  • If blocks should be split across multiple lines if it is anything more complex than one simple command after the If clause.
    If/Else should always be split.
  • Please try to line up according to the existing code:
    Parameters under parameters; or indented by two if complicated (like using CStr or parameters, etc).
    Example:
         If <blah> Then MsgBox "This is an example of a " & _
                               "really long parameter!", _
                               vbExclamation + vbOKOnly
  • The effective editor width (with panels and stuff visible) on an 800x600 screen is 66 characters. You should strive to split your lines to fit within this, as this is the default 'viewport', and anything off of this may require scrolling.
    For purposes of hardcopy, under NO circumstances should any single line exceed 76 characters.
  • VB supports PROCEDURAL PROGRAMMING. You should ONLY use the GoTo command in error handling; and you should NEVER use GoSub.
    I'm not a big fan of Djykstrya (or however you spell it), but I did grow up in the '80s and saw some totally abysmal messes that were nothing but GoTo and GoSub (fair enough, the crappy BASIC implementations offered nothing better, but you can't use that excuse any more!).
  • It is recommended that you 'wrap' your code changes in a stamp that contains your name, the program version, and the date; plus a comment that explains what has been added.
    I will leave the format up to you.
  • If you fundamentally change a section of code, it is recommended that you comment out the ORIGINAL code and say why it has been changed. Sarcasm is acceptable. ☺
  • The marker "##TODO##" (hash-hash-tee-oh-dee-oh-hash-hash) is universally used as a marker to draw attention to 'known' things that are to be looked at some other time. Look in the CPU65C102 source, you'll see a few...
  • There is no law against Easter Eggs. In fact, Easter is a good excuse to pig out on chocolate, oh yes!
  • Please do not use single-letter variable names, or give variables names of the characters in Gossip Girl etc... try to make them reflect what they are for!
    I don't use that odd notation where variables describe their type (like "uiJobStatus" where "ui" is unsigned int, etc).
    By habit, I use a variable called "Recurse" for loops. I also use things like "MyByte" for local variables inside small functions. Never something like that with global scope!
  • If the bit of code you are writing is not immediately clear, add comments!
    If you are doing something 'unusual', comment anywhere this oddity may crop up.
    For an example, I 'flip' the meanings of the FDC lines (in MiscFunc.bas) because the lines are active low but this means True is False which is confusing. So FDCTest=True means it is ON. If you look in the code, you'll see plenty of reminders to say the status has been inverted so I don't read the datasheet sometime later on and code for "yes=False". :-)
  • All dates that I write are in an ISO8601ish form, that's YYYY/MM/DD (aka "like the Japanese do it"). It is recommended that you use such formatting for consistency, however in all other cases, the date will be assumed to be in European format (DD/MM/YYYY) unless it is obvious otherwise - thus 05/11/2009 will be understood as the 5th of November.
  • This project will work with either VisualBasic 5 or VisualBasic 6.
    If you load a VB6 version into VB5, you may see the following error:
    You can ignore this (i.e. click Yes), it isn't important.
  • Any code submissions (i.e. using VB.Net etc) that cannot be loaded into either VB5 or VB6 will be discarded.
PS: If you think this is a mouthful, go read the coding practice suggestions for Ghostscript! :-)

 

 

I should not have to say this, but...
It is strictly forbidden to:

  • Insert (or modify) code in order to cause a detrimental effect to the user's computer.
  • Delete any file(s) outside of our application directory without guidance (i.e. if the user specifically wants to recreate "C:\myeprom.img"...).
  • Send any personal information whatsoever to a remote server either by direct socket access or by URL call, etc.
    It is acceptable to embed the application ID/version in the link URLs for the aid of PHP scripting to auto-notify the user if they are using an 'old' version, but that is all.
    [by this I mean a URL like .../emulator.html?app=filestore&ver=131 or such]
  • With the specific exception of redirecting to a server hosted on the development machine if the software is running on said machine (see OpenURL function), all URL calls must go to where the user is led to believe they go to. For example if the icon says "www.mysite.org/fsem/" then that's where the browser should go, and not "www.sexsexsex.com".
    Furthermore, a linked site should have neither pop-ups or sponsored adverts/images. Those things are cack and people generally dislike them, hence why 'smarter' software has options to disable this sort of thing.
  • Introduce foreign executables into the system. This software should be self-contained and not have any requirement to load/run/start any other EXEs. [starting the web browser is done by the OS, not us!]
The end user has placed trust in us that our program may or may not work exactly as intended, however it will make an attempt to do what it's description says and won't willfully compromise either their system or their identity. Respect that.

 

Return to FileStore emulator


Copyright © 2009 Rick Murray