Which is the Best Style for Easy to Understand CX Examples?

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
643
I am working on the docs to make them more beginner friendly. At the moment I try to rewrite/modify some basic examples and I wonder what style concerning naming of variables, functions, classes, objects is the best. I try to write them as consistent as possible, so this decision is pretty important at this point.

Style 1: MySomething
myVariable, myFunction, myClassObject
someVariable, SomeClass, someClassInstance

Pros: It is clear, wich kind an identifier describes. No confusion about that.
Cons: Variables should have the purpose in its name. A lot of potential confusion because everything looks like keywords.


Style 2 : Nontechnical context
Variables: age, price; Classes: SuperHero, Frog; Functions: FightEnemy, GoSwimming

Pros: Pretty good destinction between keywords and custom identifiers. Nice Stories can be told. Freedom of naming is obvious.
Cons: Kind of Identifier needs some guesswork. Storytelling talent needed.


Style 3: Mixture of kind and purpose
Variables: varPower; Classes: ClassVehicle, Method: MethOpenDoor
Variants Variables: v_Age, Functions: F_ClearPlanet

Pros: Best of both worlds ;-)
Cons: Can look awkward. Might get verbose. Could be confused with fixed naming rules like text$


Another way could be to give an example with style 1 to emphasize syntax and structure, followed by a near real world example to show purpose and proper naming.

Thoughts and ideas are welcome!
 

Dubbsta

Active member
Joined
Jul 13, 2017
Messages
202
as a beginner 2 and 3 stand out to me as easier to read
i think short examples help alot too
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
Personally I don't like the varX or methodMove() idea because it's redundant - why type Method methodMove:void()?

It's like using a prefix to indicate type (I used to do this a lot in Blitz Basic) for example iX for an integer or fX for a float but it's not necessary with CX.

My preference is for camel case with only classes having an initial capital as they are essentially types and so match the case of 'Float', 'Int' , for example...

Class Particle()
Local expiryTime:Int

I don't see anything wrong with short names when they are obvious - such as 'x' for a position or 'i' for an index etc otherwise use short descriptive names: 'age' rather than 'a', 'avg' or 'average' rather than 'a' etc. Words with underscores look ok to me so...

Local restart_time: Int
Method update_npc:Bool()

or things like:
Method updateNPC:Void()

I'm sure everyone has their own preference, I would just aim for clarity, avoid redundancy and above all be consistent.

I would also make sure all examples conform to Strict usage.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
643
no stuff like

Local image:Image

I am completly fine with that.
Thanks for your thoughts. Clarity is definitely the way to go, but not easy to accomplish.
It is hard to put yourself back in the position where code just looked like random words mixed in with brackets and dots.
Please keep in mind, that the best way to name stuff in a real world project is not necessary the best way to use for explaining the workings of code.
 
Last edited:

Gerry Quinn

Active member
Tutorial Author
Joined
Jun 24, 2017
Messages
151
I like 1 or 2. The last seems to me like a weird variation on Hungarian notation, which is not well-thought of these days.

An advantage of 1 is that they ARE actually named for their purpose, since the purpose is explaining what classes, methods etc. are for.

However, 2 tells you something of this as well, because of the meaning and parts of speech used for the names. I think overall it is the best.
 

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
912
It's an easy choice for me, number 2!

I agree with
Local image:Image

Style 1 have similar problems for beginners, if you ask me.
Another thing is that it quickly becomes too verbose.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
643
like a weird variation on Hungarian notation
I had to look it up to be honest and after reading a book about code readability I tend to go a route nearer to the original Hungarian Notation. something like appleCnt or userIndex for numbers, isReady for boolean and dogSprite for on screen objects. It is still more like style 2 than the others, because it is less technical and more purpose driven.
 
Last edited:

dawlane

Well-known member
CX Code Contributor
Joined
Jun 21, 2017
Messages
852
My two pence worth.

Modules and Files:
Modules and their file names should always be in lower case, as not all targets are case insensitive. For example on Linux project/myFile.cxs and project/myfile.cxs would be two different files within the same directory and cause no end of trouble on a non case sensitive file system.

All Cerberus source and document files edited outside the IDE must be edited with a text editor that supports utf-8 character encoding and Unix style Line Feed (LF) line endings.

VARIABLES:
See https://www.cerberus-x.com/cxDocs/Programming_Language reference.html#naming first.

All variables that are not self descriptive should have a comment to give an indication of it's purpose.

Constant variables and enumerations should be in upper case with underscores as space delimiters where applicable.
Cerberus:
Const CONST_MYCONST:Int=1    ' Constant variable for whatever.

Local, member and parameter variable should be kept short as possible, lower case and only camel case to emphasise a primary affect.
Cerberus:
Local mycnt:=0        ' A integer counter for whatever.
Field xPos:Float    ' Member variable to hold the horizontal position.

Private class member variables should start with an underscore as a quick way to identify a private member variable.
Cerberus:
Private
    Field _prvtdata        ' Member variable that should not be accessable out side the module.
All variables should not be a match for keywords, class, functions or methods.
Cerberus:
Local image:Image        ' Valid, but there is a chance that image and Image can get mixed up.
Local img:Image            ' A better way to do it.

If necessary, a form of Hungarian notation can be used. For example, prefixes with no more than three letters with underscores if desired:
str for strings types: strMyString or str_myString​
int for integers types: intMyInteger or int_myInteger​
flt for floats types: fltMyFloat or flt_myFloat​
ary for arrays: aryMyArray or ary_myArray​
bln for boolean types; blnMyBoolean or bln_myBoolean​
cls for class types: clsMyClass or cls_myClass​
lst for list containers: lstMyList or lst_myList​
stk for stack contaniners: stkMyStack or stk_myStack​
map for map containers: mapMyMap or map_myMap​
pl for pools: plMyPool or pl_myPool​
mbr or fld for class member variables: mbrMyClassMember or mbr_myClassMember or fldMyClassField or fld_myClassField​
shorten version of common module names, such as img for Image: imgMyImage or img_myImage​
obj for any type of object.​
Functions, Methods and Classes:
All functions, methods and classes that are not self descriptive should have a comment to give an indication of it's purpose.
A suggested format should be something like:
Cerberus:
'####################################################
' FUNCTION SomeFunction:Int( param1:Int, param2:Int )
' Description: Myfunction passes two integer parameters to add together and returns an integer as a result.
'    param1: First param to pass for addition
'    param2: Second param to pass for addition
Function SomeFunction:Int( param1:Int,parm2:Int )
    Return param1 + param2
End

All functions, methods and classes should be Pascal case with classes having a letter identifying that it is a custom class and not part of any core Cerberus module.
Cerberus:
Function MyFunctionName:Void()

Class CMyCustomClass

Class CImage Extends Image

READABILITY:
See https://www.cerberus-x.com/cxDocs/Programming_Language reference.html#codelines for multiple lines of code first.

Cerberus:
' Note the spaces within the parenthesis to make it a little clearer.
Method MyMethod:Int( param:String,val:Int )

' Care should be taken when calling functions that call a function as one of the parameters.
' as it's easy to loose track of the parenthesis brackets. Sometimes it's best to spread such things over multiple lines.
FileType( MyFunction1( MyFunction2( MyFunction3() ) ) )[/ICODE]

Function and method definitions and calls with multiple parameters can be spread over a number of lines.
CallMyFunction( param1,
                param2,
                param3 )

The same can be applied to arrays, numerical and logical operators.
Cerberus:
Local myIntArray:Int[] =[ $01,$05,
                          $15,$50]
                 
Local str:= "one" +
            "two"
 
Last edited:

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
912
I like to always define variables, fields and constants with type / structure and a linecomment.

I do this Because I find that putting the structure and type in a variablename do mess things up quiet a bit.
Still, you need fast access to that kind of information while programming.

Cerberus:
Local thisvariable:Int = 1 ' thisvariable is used keep track of something important in the game.

If you could just hover over any variable in the IDE to show its definition line, that would solve this problem perfectly.

You would have short names, and all access to what they are.
An alternative would be to use symbols inside the names instead of short mnemonics.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Messages
3,165
Have fun rewriting the whole api of CX.

Because if you do this for examples and tell the user how to write code in our documentation, then CX and its API need to deliver the same principals.

Anyway just my two cents. What the user wants, regulary rules the business.

Oh i would love something like

fncDrawImage(clsMyImage)

Or even better

clsMyCanvas.mthDrawImage(clsMyImage)



Local clsMyHttpRequest:clsHttpRequest = New clsHttpRequest(itfMyHttpRequestInterface)

Now that is a good one.
 

dawlane

Well-known member
CX Code Contributor
Joined
Jun 21, 2017
Messages
852
Because if you do this for examples and tell the user how to write code in our documentation, then CX and its API need to deliver the same principals.
I don't think anyone would notice, as it's never been consistent to start with. I remember someone complaining about that back in the old MonkeyX forum. I've been tempted a few times to redo the job lot in strict mode and try to fix that issue.

What the user wants, regulary rules the business.
Shame Mr S. didn't think like that. BlitzMax would have been the tool everyone would have been still using if not for his foray into other languages.

Local clsMyHttpRequest:clsHttpRequest = New clsHttpRequest(itfMyHttpRequestInterface)
I think that would be going just a bit over the top.
 
Last edited:

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
912
KISS is the way to go, standards always creates verbose "solutions".
I say, back to BASICs..
 

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
912
Look at the documentation since Monkey1/2 started.

Both the command set and the API carries a HUGE baggage.

Of course you don't need all that but it scares newcomers, because you don't know from the start exact what you need to learn! And after that, you do not need much of it anyways. And seriously, as experts or any level of programmer, how many of those have you used?

I've personally have used like 50-60 commands and API calls in total. The rest is totally unused.
But the amazing value lies in those very few words/API calls, and that they DO work in Android, iOS, macOS, Windows, Linux, and Web alike.

I'm talking about having examples that in tight code shows everything that makes up the skeleton e.g. the window/display routines, the I/O events, callbacks, timers. Because all those are important to know throughly. I/O would mean things like Files, Touch events, Admob, Joysticks and maybe not much more. Just the powerful simple graphics commands that are flexible, and yes those exist already. But they are hidden in a sea of useless plethora of functionality, that no-one will have the energy to learn (I'm not lazy, and this is so very true in my case).

All those other hundreds of commands and API's shouldn't be needed to be there at all IMHO.

Think of how much easier it would be?!
But it *should* be easy to add own commands (platform code and low level things when you feel comfortable to do it), and it should be easy to share these so you can pick och choose without namespace problems.

A really small language..

Those are my two cents :cool:
 

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
912
Data structures should be the only "troublesome" area for users.
I mean we need know how to use different structures *effectively*, when does it cost? when to use what kind of data structures and how to mix them? That's the only big problem we should need to deal with. And it deserves a big portion of this forum if you ask me.
 

Holzchopf

Moderator
3rd Party Module Dev
Tutorial Author
Joined
Jul 31, 2017
Messages
496
I prefer style 2.

Due to my lack of time, I just had a quick glance at the rest of your posts, so please excuse me if I state something meaningless now: But I don't see a reason to overhaul the Cerberus X naming conventions at this point.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
643
I don't see a reason to overhaul the Cerberus X naming conventions
Yes, the thread is drifting in that direction. I even don't think this is necessary. To me naming is structured as followed: There are naming rules that have to be follewed for your code to work properly. As a subset of names allowed there are the naming convention words that keep code constistent and readable to a certain degree. And after that as a third subset there are ideas to follow for examples to serve not only as a role model for good practice but foremost to show the workings and structure of code in an unambiguous way.
 
Top Bottom