Ultimate Amiga

Network Boards => AMOS Professional Re-Development => AMOS Factory => General Discussion => Topic started by: MadAngus on November 28, 2012, 01:20:07 PM

Title: Coding standards general discussion.
Post by: MadAngus on November 28, 2012, 01:20:07 PM

Coding standards general discussion.

For coding standards covering such things as prefixes and suffixes I'll need to dig out some industry standards and tweak them to this project and for the languages used:
For this sort of thing:
   e.g. Prefixes:
      m = Module level
      g = Global/Public

Yes I know lots of code will have to be re-factored but this will be necessary to ensure all developers can read each others code.

Also commenting of code is compulsory, as in many cases it will be quicker to re-right the code rather than attempting to decipher the authors algorithms.

This will not be one of those Open-Source projects that the only way to understand the code is for each developer to figure it out for themselves, seen too many projects fail because of this. From the code comments full developer/contributor documented will be written by myself, bruceuncle and/or any other volunteers.

Below I have provided some Module and Function Header guidelines (also provided as an attached text document):

Developers must provide the minimum headers although the full headers would be preferred for documentation purposes. Developers at their own discretion can provide headers at a level between the minimum and full version, albeit in the specified format.

Of particular note is the copyright and license these must be filled in otherwise the code will not be accepted. Please do not use the Public Domain moniker. At a minimum the license should be BSD two clause, no advertisement clause. I have attacked the OSI 'BSD two clause' and 'BSD two clause' templates if you wish to use these.

This will have to be tweaked for the language used whether it be C or assembler:

Module Header

Full Module Header
*-----------------------------------------------------------------------
*-- Module        : [Module File Name]
*-- Description   : [Primary purpose of the module]
*-- Copyright (C) : [Name of copyright holder]
*-- Author        : [Names of Programmers/Authors]
*-- License       : [Module License]
*-- Created       : [First Release Date]
*-- Last Modified : [Latest Revision Date]
*-- REVISION      : [Revision Number]
*-- Notes         : [General information/instructions for the programmer]
*--               :
*-- Written for   : [Name of target application]
*-- Rev. History  :
*--               : [Release Date] -- Original.
*--               : [Release Date][ -- ][Update summary]
*--               :              [ -- ][Update summary cont.]
*--               :
*-- Instantiation :
*--               :[Instruction/steps necessary to include/call this module]
*--               :
*-- Dependencies  :
*--               :[Required libraries/modules to compile/use this module]
*--               :
*-- Methods       :
*--               : [Method Name (args)]
*--               : - [Short Method Description]
*--               :
*-----------------------------------------------------------------------

Example Full Module Header
*-----------------------------------------------------------------------
*-- Module        : INITIALISEAPP.PRG
*-- Description   : Initialises the ExGames database
*-- Copyright (C) : Joe Gilmour
*-- Author        : Joe Gilmour
*-- License       : BSD
*-- Created       : 07/03/2002
*-- Last Modified : 17/04/2002
*-- REVISION      : Revision:  0.04
*-- Notes         :
*--               : Contains routines to:
*--               : Initialise all forms, array and objects on application startup.
*--               :
*--               :
*-- Written for   : dBASE for Windows 5.7
*-- Rev. History  :
*--               : 07/03/2002 -- Original.
*--               : 01/04/2002 -- Added arrays for initialising game review data.
*--               : 04/04/2002 -- Added arrays for initialising collectors notes data.
*--               : 17/04/2002 -- Optimized code, Used "NEW Array (rows, cols)" instead of
*--               :             using the grow method to set the size of arrays.
*--               :
*-- Instantiation :
*--               : set procedure to initialiseapp.prg additive
*--               :
*-- Dependencies  :
*--               : center.prg
*--               :
*-- Methods       :
*--               : Procedure FindGameName(SearchMethod, SearchGName)
*--               : - Check for a games existance
*--               :
*-----------------------------------------------------------------------

Minimum Module Header
*-----------------------------------------------------------------------
*-- Module        : [Module File Name]
*-- Description   : [Primary purpose of the module]
*-- Copyright (C) : [Name of copyright holder]
*-- Author        : [Programmer/Authors name]
*-- License       : [Module License]
*-- Created       : [First Release Date]
*-- Last Modified : [Latest Revision Date]
*-- REVISION      : [Revision Number]
*-----------------------------------------------------------------------

Example Minimum Module Header
*-----------------------------------------------------------------------
*-- Module        : INITIALISEAPP.PRG
*-- Description   : Initialises the ExGames database
*-- Copyright (C) : Joe Gilmour
*-- Author        : Joe Gilmour
*-- License       : BSD
*-- Created       : 07/03/2002
*-- Last Modified : 17/04/2002
*-- REVISION      : Revision:  0.04
*-----------------------------------------------------------------------


Function/Procedure Header

Full Function/Procedure Header
*-----------------------------------------------------------------------
*-- Function      : [Function Name]
*-- Description   : [Primary purpose of the module]
*-- Copyright (C) : [Name of copyright holder]
*-- Author        : [Names of Programmers/Authors]
*-- License       : [Module License]
*-- Created       : [First Release Date]
*-- Last Modified : [Latest Revision Date]
*-- REVISION      : [Revision Number]
*-- Notes         :
*--               : [General information/instructions for the programmer]
*--               :
*-- Written for   : [Name of target application]
*-- Rev. History  :
*--               : [Release Date] -- Original.
*--               : [Release Date][ -- ][Update summary]
*--               :              [ -- ][Update summary cont.]
*--               :
*--               :
*-- Calls         :
*--               : [Other modules/functions this function calls]
*--               :
*-- Called by     :
*--               : [Other modules/functions this function is called by]
*--               :
*-- Usage         :
*--               : [Instruction/steps necessary to include/call this function]
*--               :
*-- Returns       :
*--               : [Returned variable and type]
*--               : - [Short description of returned variable]
*--               :
*-- Parameters    :
*--               : [Parameters/Arguments used by this function]
*--               : - [Short description of parameter/argument]
*--               :
*-----------------------------------------------------------------------

Example Full Function/Procedure Header

Procedure UpdateGameSet(GameIDNum)
*-----------------------------------------------------------------------
*-- Function      : UpdateGameSet
*-- Description   : Saves an updated game entry to the database
*-- Copyright (C) : Joe Gilmour
*-- Author        : Joe Gilmour
*-- License       : BSD
*-- Created       : 10/03/2002
*-- Last Modified : 05/04/2002
*-- REVISION      : Revision:  5
*-- Notes         :
*--               : Saves an updated game entry to the database tables from data stored in the arrays.
*--               :
*-- Written for   : dBASE for Windows 5.7
*-- Rev. History  :
*--               : 11/03/2002 -- Original
*--               : 12/03/2002 -- Added arrays for initialising admin data.
*--               : 01/04/2002 -- Added arrays for updating game review data.
*--               : 05/04/2002 -- Added arrays & Code to update collectors notes data.
*--               : 23/04/2002 -- Split code into two procedures one for initialising the arrays and
*--               :             one for saving the array values to the database
*--               :
*-- Calls         :
*--               : None
*--               :
*-- Called by     :
*--               : Any
*--               :
*-- Usage         :
*--               : UpdateGameSet(GameIDNum)
*--               :
*-- Returns       :
*--               : None
*--               :
*-- Parameters    :
*--               : GameIDNum
*--               : - index number of the game to update
*--               :
*-----------------------------------------------------------------------

Minimum Function/Procedure Header
*-----------------------------------------------------------------------
*-- Function      : [Module File Name]
*-- Description   : [Primary purpose of the module]
*-- Copyright (C) : [Name of copyright holder]
*-- Author        : [Programmer/Authors name]
*-- Created       : [First Release Date]
*-- Last Modified : [Latest Revision Date]
*-- REVISION      : [Revision Number]
*-----------------------------------------------------------------------

Example Minimum Function/Procedure Header
*-----------------------------------------------------------------------
*-- Function      : UpdateGameSet
*-- Description   : Saves an updated game entry to the database
*-- Copyright (C) : Joe Gilmour
*-- Author        : Joe Gilmour
*-- Created       : 07/03/2002
*-- Last Modified : 17/04/2002
*-- REVISION      : Revision:  0.04
*-----------------------------------------------------------------------

Title: Re: Coding standards general discussion.
Post by: MadAngus on November 28, 2012, 01:21:20 PM

Copied from bruceuncles post:

Quote from: MadAngus on November 25, 2012, 04:08:50 PM

For coding standards covering such things as prefixes and suffixes I'll need to dig out some industry standards and tweak them to this project and for the languages used:
For this sort of thing:
   e.g. Prefixes:
      m = Module level
      g = Global/Public

Yes I know lots of code will have to be re-factored but this will be necessary to ensure all developers can read each others code.

Also commenting of code is compulsory, as in many cases it will be quicker to re-right the code rather than attempting to decipher the authors algorithms.

Great stuff for C and ASM.  No problems with space in those environments for copiously commenting the code.

But AMOS is an altogether different environment.  There's a need with large programs for a 'comment culler' to cut the size down.  So you end up with two copies - one commented, the other uncommented.   This would be a very different case if the AMOS Compiler worked reliably!  But we'll fix that won't we?

I've suggested some standard in the introduction for the AMOS Reference Manual.  This is an extract of the Variables topic where I make some suggestions with the reasons why:

Variables

AMOS Basic Variables must follow these rules:

• Variable Names must begin with a letter.
• The only characters that can be used in a Variable Name are upper-case letters, numbers and the underscore (_).  A single character suffix of # or $ is allowed and denotes the variable's type.
• A Variable Name with no suffix is an Integer type.
• A Variable Name with a # suffix is an Single- or Double-Precision type.
• A Variable Name with $ suffix is a String type.
• The maximum length for a Variable Name is 255 characters.
• A Variable Name must not begin with the characters from an AMOS Keyword.  E.g. PRINTER_NAME is illegal as it starts with the AMOS Basic Instruction Print.

Note that there is no requirement to define a Variable before it is used (the Dim statement used in other Basic dialects has a completely different meaning).  So, in long programs it is very easy to mis-type a Variable Name without the mistake being picked up when the program, is checked.
As AMOS Basic can use both Global and Local Variables, it is strongly recommended that some Naming Convention is used, especially for long programs.  Otherwise, it can be difficult to keep track of the scope of each Variable.
Using a prefix convention is especially useful as it avoids any problems with Variable Names beginning with AMOS Basic Keywords.  Note that any Extensions added after a program has been written may give problems as it will add a whole new set of Keywords.  Some of these may clash with previously legal names unless a prefix convention has been used.

Suggested Naming Convention
The Naming Convention show below is just a suggestion as to what may be appropriate:

G_	A Variable with Global (or Shared) Scope.
L_	A Variable with Local Scope.
P_	A Parameter for a Procedure (used in the Procedure's definition).
F	Used in conjunction with any of the above, a Boolean or Flag Variable that only has values of True or False.  E.g.  PF_ would denote a Boolean Parameter.
C	Used in conjunction with any of the above, a Constant.  AMOS Basic has no constant declaration statement as used in some other dialects of Basic.  However it is sometimes useful to use a Variable to do the job of a Constant.  E.g.  GC_MAX_LENGTH=30 might be used so that all code using that value (30) uses the Variable Name GC_MAX_LENGTH instead.  The code is easier to read and, if the value of 30 is changed later in development, it only needs to be changed in one place.

For Procedures and Labels the same naming rules apply.  And there is the same problem of avoiding Procedure Names that begin with an AMOS Basic Keyword.  Using an underscore (_) as a prefix to all Procedure and Label Names avoids this.
Some examples:

     Rem Examples of a Naming Convention
     Rem This is NOT a program - don't try to run it!
     Global G_HIGH_SCORE
     G_HIGH_SCORE=0
     '
     Global GF_SHIELD_ON
     GF_SHIELD_ON=False
     '
     Global GC_MAX_ALIENS
     GC_MAX_ALIENS=15
     '
     Procedure _DO_INVENTORY[PF_INCLUDE_SPELLS]
     '
     If X>GC_MAX_X Then Inc DX:Dec X

Having just written (still am) a long, long AMOS Basic program, the above rules have made it a lot easier to keep track of what's being used and where.  The point about no variable declaration and checking is very important.  Without careful docs and partitioning, the whole thing can become a nightmare of spaghetti code.

I'll have some software ready for release this side of Xmas.  So see what you think of the sources.

Title: Re: Coding standards general discussion.
Post by: Lonewolf10 on January 05, 2013, 12:31:59 AM

[Edit by MadAngus] Just to avoid confusion this post is aimed at bruceuncle, the above post was copied from his post elsewhere.

Quote from: MadAngus on November 28, 2012, 01:21:20 PM

Having just written (still am) a long, long AMOS Basic program, the above rules have made it a lot easier to keep track of what's being used and where.  The point about no variable declaration and checking is very important.  Without careful docs and partitioning, the whole thing can become a nightmare of spaghetti code.

How many lines of code? I have written a few that have 3000 lines of code.

Quote from: MadAngus on November 28, 2012, 01:21:20 PM

I'll have some software ready for release this side of Xmas.  So see what you think of the sources.

erm... unless I missed it, it'll be the other side of Xmas now... ;D

Title: Re: Coding standards general discussion.
Post by: bruceuncle on January 05, 2013, 12:56:39 PM

Quote from: MadAngus

erm... unless I missed it, it'll be the other side of Xmas now...

Had a lousy December, a bl**dy good Xmas and then stuffed my back big-time for New Year.  Only just able to again sit at a PC for more than 5 minutes.

I'm overloaded to blazes now with everything running late!  Whilst incapacitated I've done more reading of Amiga and AMOS tech material than is good for me  ::).  Luckily, the wife bought me a couple of good novels for Xmas.

Quote from: Lonewolf10

How many lines of code? I have written a few that have 3000 lines of code.

Currently 4,204 lines of code.  Plus 307 for the program that generates the Data Bank and 343 for the program that generates the Menu Bank.  However, the  long-winded versions of the DBL programs (in AMOS Basic strings) are still in there until they're ready to stuff into the Resource Bank.

Current status:

Completed

• The chroma-coded editor all working in very similar fashion to the AMOS Editor (menus, keys, etc).
• Block highlighting and tracking all working.
• Load and save in *.DBL format (straight ASCII DBL Code).
• Load and save in *.ASC format (ASCII DBL Code in AMOS Basic A$=A$+"blah, blah, blah" format c/w DBL Comment conversion to AMOS Basic Comments and vice versa).
• Auto EOL character detection on file load with optional manual override for saves.
• Load Target Resource Bank and pull to pieces, substituting Default resource numbers where no Images and/or Messages are in the target.
• Comments format for both *.DBL and *.ASC formats.
• DBL Expansion fully working.
• Syntax Template Insert fully working (and with placeholders for you to fill in  :)).
• Clean exit with bank clean up fully working.

In Progress

• Insert utility for the default Editor Message Numbers (all the negative ones that no one realises are already there for the asking  ;)).
• DBL Compression (to the unintelligible format that gets stuffed into the Resource Bank - modification of the method already in the Resource Bank Maker accessory).
• Insert dialogues for Image and Message Numbers (similar to the Syntax Template Inserts but showing what's available in the Target Resource Bank or Default Resource Bank - saves having to print them out or jot them down on scraps of paper).  Also allows the Messages to be edited (unless they're sourced from the Default Resource Bank!).

To Do

• Move DBL Programs between the loaded Target Resource Bank and the Editor and vice-versa.  Naming, moving, etc.
• Save the loaded Target Resource Bank.  Recreate the bank (modification of the methods already in the Resource Bank Maker accessory).
• Cut, Copy and Paste code (data structures and housekeeping already in place).

Sounds like still a lot to do before the beta release.  But most of it's just joining the 'Lego blocks' together.  The Cut, Copy and Paste's the only bit remaining to be done from scratch.

I was pleased to see that the original AMOS Team also referred to these programs as DBL code in the sources  :D

Learnt more about AMOS than the manuals, help files or sources could ever have taught me.  Good fun when my back's not killing me!

Title: Re: Coding standards general discussion.
Post by: Lonewolf10 on January 05, 2013, 11:54:13 PM

Quote from: bruceuncle on January 05, 2013, 12:56:39 PM

Quote from: MadAngus

erm... unless I missed it, it'll be the other side of Xmas now...

Had a lousy December, a bl**dy good Xmas and then stuffed my back big-time for New Year.  Only just able to again sit at a PC for more than 5 minutes.

No problem. My dad did his back in last summer, so I totally understand what that is like (minus the pain though). Sounds like you are starting to know more about AMOS than me :)

Title: Re: Coding standards general discussion.
Post by: MadAngus on January 22, 2013, 12:54:48 AM

Is Reply #2 to #4 seems to be off-topic, please advise otherwise before I split.