Home

Map

OS++ Down Load

Doco_A

Youtube

Chat

News

Shop

//#! Declaration: http://osplusplus.org/2022standard/Professional

//#! Language documentation - http://osplusplus.org/2022doco

TLDR; This is the standard you want to see. It means that the code has been written to industry standard and therefore readable.

The excuse declarations are as follows:

• http://osplusplus.org/2022standard/Amateur
• http://osplusplus.org/2022standard/Technical_deficit
• http://osplusplus.org/2022standard/Privilege
• http://osplusplus.org/2022standard/Prehistoric
• http://osplusplus.org/2022standard/Kludge
• http://osplusplus.org/2022standard/Throwaway

The Standards declarations are as follows:

• http://osplusplus.org/2022standard/Professional
• http://osplusplus.org/2022standard/Shop
• http://osplusplus.org/2022standard/User_defined

Quick questions

The 80/20 summary

Professional grade Code conforms to the accepted industrial standard for the 2022 version of OS++.

Shop grade The companies interpretation of that standard. To be used in house.

Amateur Author is learning and trying out the language. This is not meant for production.

Technical_deficit Author is under a time pressure and will fix later when time allows

Prehistoric - Old Code, that just works. Does not expect to be updated. Mark it Prehistoric. Let sleeping dogs lie. Move on.

Introduction

There are multiple Grade declarations for this language. The declaration at the top tells the reader what to expect.

Grades are:

1. Professional
   • Standard created by industry best practise
   • Code written by a professional developer
   • Can go into production and meets all professional standards
   • Can be scanned by development DBA to ensure it conforms to standard
   • Meets the industry standard for the language.
   • The intention is to create a product that can be worked on by any professional in the field
     So you can be replaced, like a cog, when you advance to management, win the lottery or have an argument with a bus.
2. Shop_standard
   • Standard created by Company or shop concerned. Probably modified Professional standard
   • Code written by a professional developer
   • Can go into production and meets all company standards
   • Can be scanned by development DBA to ensure it conforms to standard
   • The intention is to allow a company to set their own standard to meet their own needs
   • A shop may have multiple standards for different projects, with different priorities.
     A public project that loses $2M per second if down, may have a different standard to an internal non financial system.
3. Amateur
   • Written by Amateur who is learning and wants to try out their ideas
   • Can Not go into Production
   • Notifies development DBA that this is a learning or fun exercise. Do not put into production.
   • The intention is to allow people to try out and learn without incurring the wrath of a DBA
   • eg. Allow gotos and other monstrosities. How else will you learn otherwise?
4. Technical_deficit
   • Written by a professional developer
   • Does NOT conform to Professional or Shop_standard
   • Requires Business authorisation to goto Production
   • Expected to have a long life in production
   • Will be rectified in a future release, when time allows.
   • The intention is to allow people to meet the realities of working in the field
5. Kludge
   • Written by a professional developer
   • Does NOT conform to Professional or Shop_standard
   • Requires Business authorisation to goto Production
   • Is a quick and dirty fix to get over “the hump”. Possibly the only technical solution viable
   • Expected lifetime to be this version only. But will probably outlast the project.
   • Will be removed in a future release
   • The intention is to allow people to meet the realities of working in the field
6. Throwaway
   • Written by a professional developer.
   • Does NOT conform to Professional or Shop_standard
   • Requires Business authorisation to goto Production
   • Expected life unknown
   • The intention is to allow people to meet the realities of working in the field
   • eg. Allow gotos and other monstrosities. For a one off project or issue.
7. Privilege
   • Written by a non professional developer. Possible a DBA, CEO or manager.
   • Does NOT conform to Professional or Shop_standard
   • Is in production because I said so and it’s my responsibility.
   • Sometimes you just have to break all the rules to keep the wheels of commerce turning
8. Prehistoric
   • Designation used for old code that was created long ago.
   • Written before the standard was used
   • Does NOT conform to Professional or Shop_standard
   • Is in production already.
   • Action? May stay for eternity. It works. Requires little maintenance. Does not need be updated with new features.
     To update it to the standard could introduce bugs (added risk) without any business benefit (no reward).
     Let sleeping dogs lie. Mark it and move on.
9. None
   • You are officially off my Xmas card list.

DBA notes

As a production DBA I have absolutely no business writing this standard. I have no standing. So until a developer can come in and write this properly with the latest patterns and lingo. This will have to do, as a stump. As a DBA I can code. But my code is ugly. I see code as a means to an end. Not an end in it’s own right. ie I create rugged utility, not works of art.

Professional standard (in detail)

The standard has many parts and includes style and function. The idea is to make the code quick and easy to write. But simple for you to debug six months down the line, without sobbing. You should never think to yourself “what manic wrote this code, are they insane?” only to find out via the change control system it was a younger & less experienced version of yourself. Some of these standards have no practical use in this language but I added them anyway.

The overall standard of code should meet “The drunk Friday afternoon standard”. That is, it should be so obvious, that someone who has had a large liquid lunch, paid for by their boss, can effectively understand and utilise the code despite the fact they are seeing almost double.

Notes. I dare say that “The age of the Friday liquid lunch” is thankfully over, with the advent of HR policies. However, it is an excellent standard to write code to in the, keep it simple, vein of dba coding. A discipline where one “wrong script parameter” can mean an unofficial and unscheduled test of the disaster recovery system.

Workflow

1. Take template and copy to your intended part_file name. eg PROJECTminisaw_motorenclosure.scad
2. Run through the template copy. Alter the necessary parts. Each section is supposed to make you think. Delete if unnecessary or irrelevant.
3. Create a list of primary data types in Global. (for all modules to see).
4. Create your masterful code, linking the primary data types together, and put in main();
5. As the code becomes more complex move chunks into other modules that main() can call. (These chunks can still see the primaries in Global)
6. Batch up all the variations of STLs (PLA/ABS recycle symbols, Plus/minus size modification) into a tar.Z and include with scad file.

Professional standard (specifics)

NB As a production DBA I have no business writing this code. This is the developers domain not mine. In the mean time here are some of my ideas. You may wish to poke fun at.

Remarks (//)

Aim to have a remark for every line of code unless it is blindingly obvious what the code does, when read in context.

eg:
// This is the body of the object and …..
cuboid_body=[10,20,30];

// This is a …… and used to …..
sphere_body=[10];

Why? Because it will help ensure readability and maintenance for years to come.

Remarks (//)

Aim to connect blocks of code, which can be thought of as a discrete block using “open” remarks ie a // on it’s own.

eg:
//
// ^^^^^ open block above
eg Block of code connected together with // and does not have any blank lines

Why?
Because it becomes blindingly obvious that all of that code is one discreet block which does a single task and needs to be read as such. When I read the code below I see debug, don’t care, don’t care, don’t care, End-debug. What does the next block do? However, if there is a clean line in the debug I have to do a context switch and ask is this is a new block of code?

/* ( rem out with // to activate ie // /*)
/////////////////////////////////////////////////////////////////
//Debug code
/////////////////////////////////////////////////////////////////
// Code blocks test to make sure valid works
// lib_cuboid_validAnchorDigit(testingDigit)=1 // true or valid
// lib_cuboid_validAnchorDigit(testingDigit)=0 // false or invalid
// 
// Assign our test case
testingDigit="P";
//
// Run code and see if we get what is expected
if (1==lib_cuboid_validAnchorDigit(testingDigit))
 {echo ("testingDigit is ",testingDigit);}
  else
 {echo ("testingDigit is invalid >",testingDigit);}
/////////////////////////////////////////////////////////////////
//End - Debug code
/////////////////////////////////////////////////////////////////
*/ ( rem out with // to activate ie // * /)

Variable names in module

When using a variable name in a module use an _ to start it

eg
_obvious_variable_name

Not
obvious_variable_name

Why?
Because if you use a descriptive name. Someone else might use it in global. Which throws an error. If you start all your variables with a _ then it is unlikely that someone using your code will use _ in global

Variable name format = object_datatype

When you create a primary object like a cuboid for the mainbody call it cuboid_mainbody.

Why ?   Because whenever you use that datatype variable you know to render it as a cuboid and not a sphere.

= DatatypeLibraryName_somethingdescriptive
eg cuboid_mainbody=[10,20,30];   // this means the datatype comes from lib_cuboid
eg cone_mainbody=["Z",5,3];      // this means the data type comes from lib_cone
eg sphere_mainbody=[4];          // a Sphere with a radius of 4
eg column_mainbody=[?????];      // this datatype comes from lib_column

Variable name format = object_datatype_useage

When you create a complex primary object, add it’s usage. eg cuboid_graphpaper_plan, cuboid_hole_minus , cone_hat_plus.
Where the usage is how you intend to use the shape.
Example - Plus (it’s a real object) , Minus (We will be taking things away with this) , Plan (we use this to position things)

Why ?
Because it helps with readability and understanding what it’s for.

/*
Primary           = Name of libray and primary objects. cuboid means lib_cuboid, which is a primary for cuboids
Description       = Anything that make sense at the time
Type (optional)   = plus, minus, plan

-- where
--- plus vs minus - plus is a positive shape, minus is a negative shape such as a drill hole
--- plan - object that places other objects in space but does not get positively or negatively rendered.
*/

End bracket etiquette

Never allow a } to alone on a line. It must have a remark.

eg } // end function,
eg } // end module
eg } // end translate. Move back to previous anchor point
eg } // end of difference, union etc

Why?
Because I don;t like running through code trying to work out my nest level.
This allows a second party to quickly under stand where they are in the code.
This allows the Author to make sure they } is connected with the correct block of code.

Translates - openscads version of goto

No direct translates.

!eg> translate([5,2,3]) // is not allowed

+eg> translate(lib_cuboid_mv([vector_derived_from_object])) // is allowed
+eg> translate(lib_cuboid_mv(“000”,cuboid_ObjectName)) // is allowed

invalid function

Function that answers the question “Is this datatype invalid?”

Return is 0 for false. ie this is a valid datatype
Return is 1,2,3,4,… for true. ie this is an invalid datatype and the number denotes why it is invalid.

Why do we do this instead of asking if the function is valid?
Because there are many reasons why something is invalid. But only one response if it is valid.

Goto, JP, JR & Gosub function

Goto are not allowed (but I am working on it)

Site summary (added to bottom of every page)