User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Readable Code Style, Review Requested.

Mon Nov 21, 2016 12:45 am

As I am working toward releasing some software that I wish to be sure is easily read by others, I would like a peer review of the readability of the style that I intend to use for the released code. As there is som minor difference between different languages, I am here asking as it refers to the implementation in ARM BASIC.

I ask as I know that normaly it is difficult for others to read my code, as my normal style developed over the last 32 years of writing code is not what most expect to see.

I hope that this is readable easily to others. Though if it is not I would apreciate any feedback on how to improve the readability.

This is just a short example of the style I intend to apply to the larger programs (that are already written, in my old way so will need modified).

Here is an Example, target OS is RISC OS, language is ARM BASIC (BBC BASIC V):

Code: Select all

REM > !RunImage
REM * Simple program to answer the question of code readability.  The prrogram
REM *   just places an Icon Sprite on the IconBar, and quits when the Icon
REM *   clicked on.   Poor example of program, good readability.
ON ERROR PRINT "LINE : " + STR$(ERL) + " ERROR : " + REPORT$ : END


_TaskMagic%      = &4B534154
_WimpVer%        =       310  :REM Minimum WIMP version.
_TaskName$       = "Readable" :REM Name for WIMP task.
_AppIcon$        ="!readable" :REM Name of IconBar Icon.
_IconSprite%     = &00000002  :REM Icon flag is Sprite.
_IconFlagClick%  = &00003000  :REM Icon Flag button type click.
_TempSize%       =       256  :REM Size of Temp Work space.
_PollFlags%      = &00002301  :REM Poll flags, for minimum CPU.

TaskHandle%      = 0
Icon%            = 0
IconHandle%      = 0
DIM TempWork% _TempSize%

PROCStart
END

DEF PROCPoll : REM *** Poll Loop, handling Poll reasons. ***************
  LOCAL quit%, reason%
  quit% = FALSE
  REPEAT
   SYS "Wimp_Poll",_PollFlags%,TempWork% TO reason%
   CASE reason% OF
   WHEN 6: :REM If clicked on our Icon, quit.
     IF TempWork%!8  = -2   THEN quit% = TRUE
   WHEN 17,18:   :REM If user message is quit, we quit.
     IF TempWork%!16 =  0   THEN quit% = TRUE
  UNTIL quit%
ENDPROC

DEF PROCStart :REM *** Our Entry Point *********************************
  LOCAL x0%,y0%,x1%,y0%,flags%,data%
  x0% = 4: y0% = 8: x1% = 12: y1% = 16
  flags% = 20: data% = 24

  SYS "Wimp_Initialise",_WimpVer%,_TaskMagic%,_TaskName$,0 TO TaskHandle%

  Icon%           = TempWork%
  !Icon%          = -1             : REM Window handle of IconBar.
  Icon%!x0%       =  0
  Icon%!y0%       =  0
  Icon%!x1%       = 64
  Icon%!y1%       = 64
  Icon%!flags%    = _IconFlagClick% OR _IconSprite%
  $(Icon%+data%)  = _AppIcon$
  SYS "Wimp_CreateIcon",,Icon% TO IconHandle%

  PROCPoll

  SYS "Wimp_CloseDown",TaskHandle%,_TaskMagic%
ENDPROC
The forums do NOT use a fixed width font, so it will look better in a traditional text editor, especialy on RISC OS (for which it is written).

I am attaching the complete application including the Sprite file and the two obey files. The attachment also contains a text copy of the source so those that do not have RISC OS may read the source code with ease.

If you intend to run this, then only unzip in RISC OS, so as to preserve file types.
Attachments
readable.zip
Simple example to determine readability.
(2.96 KiB) Downloaded 118 times
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
scruss
Posts: 1305
Joined: Sat Jun 09, 2012 12:25 pm
Location: Toronto, ON
Contact: Website

Re: Readable Code Style, Review Requested.

Mon Nov 21, 2016 1:31 am

Underbar prefixes read as private object methods to me. I don't find BBC BASIC's pointer syntax remotely easy to read, but there's not much anyone can do about that.
‘Remember the Golden Rule of Selling: “Do not resort to violence.”’ — McGlashan.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Mon Nov 21, 2016 3:00 am

scruss wrote:Underbar prefixes read as private object methods to me. I don't find BBC BASIC's pointer syntax remotely easy to read, but there's not much anyone can do about that.
I do not wqant to use all upercase for defined values, as it runs the risk of accedently including a keyword in the name, and that can be a problem in BBC BASIC.

Would it be easier to read if I used the Grave character? As in:

Code: Select all

`TaskMagic%      = &4B534154
`WimpVer%        =       310  :REM Minimum WIMP version.
`TaskName$       = "Readable" :REM Name for WIMP task.
`AppIcon$        ="!readable" :REM Name of IconBar Icon.
`IconSprite%     = &00000002  :REM Icon flag is Sprite.
`IconFlagClick%  = &00003000  :REM Icon Flag button type click.
`TempSize%       =       256  :REM Size of Temp Work space.
`PollFlags%      = &00002301  :REM Poll flags, for minimum CPU.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

ejolson
Posts: 1021
Joined: Tue Mar 18, 2014 11:47 am

Re: Readable Code Style, Review Requested.

Mon Nov 21, 2016 4:55 am

DavidS wrote:
scruss wrote:Underbar prefixes read as private object methods to me. I don't find BBC BASIC's pointer syntax remotely easy to read, but there's not much anyone can do about that.
I do not wqant to use all upercase for defined values, as it runs the risk of accedently including a keyword in the name, and that can be a problem in BBC BASIC.

Would it be easier to read if I used the Grave character? As in:

Code: Select all

`TaskMagic%      = &4B534154
`WimpVer%        =       310  :REM Minimum WIMP version.
`TaskName$       = "Readable" :REM Name for WIMP task.
`AppIcon$        ="!readable" :REM Name of IconBar Icon.
`IconSprite%     = &00000002  :REM Icon flag is Sprite.
`IconFlagClick%  = &00003000  :REM Icon Flag button type click.
`TempSize%       =       256  :REM Size of Temp Work space.
`PollFlags%      = &00002301  :REM Poll flags, for minimum CPU.
I vote for the underscores, or maybe a capital D instead.

User avatar
scruss
Posts: 1305
Joined: Sat Jun 09, 2012 12:25 pm
Location: Toronto, ON
Contact: Website

Re: Readable Code Style, Review Requested.

Mon Nov 21, 2016 3:59 pm

Keep the underscores, then. I'd forgotten about case in BBC BASIC.

The code is very low level; aren't there higher level constructs available that would avoid you having to explain the contents of the bit fields in (for example) _PollFlags% and TempWork%? Are there functions to create a button from an image, without having to explicitly say how big the image is? F'rinstance, in tcl, the code to do what your example does could be something like this:

Code: Select all

#!/usr/bin/tclsh
package require Tk
image create bitmap excl -data "#define excl_width 16\
 #define excl_height 24\
 static char excl_bits[] = {\
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\
 0x00, 0x00, 0x00, 0x00, 0x00, 0x7c,\
 0x3c, 0x38, 0x08, 0x70, 0x04, 0xe0, 0x02, 0xc0, 0x01,\
 0x80, 0x03, 0x40, 0x07, 0x20, 0x0e,\
 0x10, 0x1c, 0x3c, 0x3e, 0x00, 0x00, 0x00, 0x00, 0x00,\
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,\
 0x00, 0x00, 0x00};"
button .b -image excl -command exit
pack .b
It's four lines long. Aside from the horrid XBM inclusion (I'm sure there are tidier ways, but not ones that fit in a forum's code box), there's really one line that does the work. It also uses fairly obvious commands to get stuff done.
‘Remember the Golden Rule of Selling: “Do not resort to violence.”’ — McGlashan.

User avatar
rpdom
Posts: 11521
Joined: Sun May 06, 2012 5:17 am
Location: Essex, UK

Re: Readable Code Style, Review Requested.

Mon Nov 21, 2016 7:48 pm

code.png
code.png (16.63 KiB) Viewed 3092 times
Hmm?

Looks fairly fixed width to me.

User avatar
PeterO
Posts: 3613
Joined: Sun Jul 22, 2012 4:14 pm

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 7:23 am

scruss wrote: Are there functions to create a button from an image, without having to explicitly say how big the image is? .
You mean like a library or tool kit ? But surely these wouldn't be portable and would waste precious bytes of memory ?
PeterO :roll:
Discoverer of the PI2 XENON DEATH FLASH!
Interests: C,Python,PIC,Electronics,Ham Radio (G0DZB),Aeromodelling,1960s British Computers.
"The primary requirement (as we've always seen in your examples) is that the code is readable. " Dougie Lawson

User avatar
GavinW
Posts: 72
Joined: Tue Nov 01, 2011 8:11 pm
Location: UK
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 2:51 pm

How does this compare for readability? It does the same - puts an icon on the iconbar and quits when you click Select on it. This is in RiscLua.

Code: Select all

local task, QUIT in require "task"
local window, ibar = require "window, require "ibar"
local example = task "IbarExample"
window.init (example)
example:init ( )
local ibaricon = ibar.icon (example, "file_xxx")
example:register ("iconbar", ibaricon) { on_Select = QUIT }
example:run ( )
otium negare negotium vanum

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:04 pm

GavinW wrote:How does this compare for readability? It does the same - puts an icon on the iconbar and quits when you click Select on it. This is in RiscLua.

Code: Select all

local task, QUIT in require "task"
local window, ibar = require "window, require "ibar"
local example = task "IbarExample"
window.init (example)
example:init ( )
local ibaricon = ibar.icon (example, "file_xxx")
example:register ("iconbar", ibaricon) { on_Select = QUIT }
example:run ( )
Does not look like BASIC. Though does look most readable.

This thread was posted in "Programming.Other Languages", what is it doing in RISC OS? It was supposed to be of benifit to all programmers in the area of readability of code.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:05 pm

This thread was posted in "Programming.Other Languages", what is it doing in RISC OS? It was supposed to be of benifit to all programmers in the area of readability of code.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:06 pm

rpdom wrote:
code.png
Hmm?

Looks fairly fixed width to me.
Not what it looks like here, unfortunately.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

stderr
Posts: 2178
Joined: Sat Dec 01, 2012 11:29 pm

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:16 pm

DavidS wrote:Does not look like BASIC. Though does look most readable.
And now for a truly shocking bit of insight.

jahboater
Posts: 1769
Joined: Wed Feb 04, 2015 6:38 pm

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:30 pm

DavidS wrote:
rpdom wrote:
code.png
Hmm?

Looks fairly fixed width to me.
Not what it looks like here, unfortunately.
What web browser are you using?
Its fixed width in Firefox.

User avatar
GavinW
Posts: 72
Joined: Tue Nov 01, 2011 8:11 pm
Location: UK
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:35 pm

What is it doing in RISC OS? Because it runs under RISC OS. That is why it is called RiscLua. You should try it.
otium negare negotium vanum

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 5:46 pm

DavidS wrote:
rpdom wrote:
The attachment code.png is no longer available
Hmm?

Looks fairly fixed width to me.
Not what it looks like here, unfortunately.
This is what it looks like here.
Attachments
blalll.gif
blalll.gif (9.57 KiB) Viewed 2700 times
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 7:04 pm

scruss wrote:Keep the underscores, then. I'd forgotten about case in BBC BASIC.

The code is very low level; aren't there higher level constructs available that would avoid you having to explain the contents of the bit fields in (for example) _PollFlags% and TempWork%? Are there functions to create a button from an image, without having to explicitly say how big the image is?.
Firstly it is not exactly a button, it is more of what other OS's call an Icon in this case (which is just one kind of Icon in RISC OS).

And secondly the Sprite is 32 x 32 pixels, not 64 x 64, though in most modes having 2x2 ratio 32 pixels is 64 OS Units. This is obvious to those that know the target arch.

Yes there are ways to use OS_Sprite to get the size, though those are just as low level as this.

And in my personal opinion when working in BASIC this is easier than any of the libraries, bessides which I would hate to have to post the giant contents of the libraries as part of a question of readability, because they would be part of the program, and you would still need to see the values being used.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 7:10 pm

@Whichever_mod_moved_this_thread:
This thread is not RISC OS specific, it is about the readability of code in general, and what steps need to be taken to insure readability of code written in any programming languag. That is why it was originaly posted in "Programming.Other Languages".

While I already started another thread in "Programming.General Programming Descusion" since I could not find this thread, it would be appreciated if this thread were put back where it fits, rather than in an OS Specific area.

I intended to add the assembly language example to this thread yesterday, when I could not find the thread, so I ignored the forum until today, as I figured some Moderator had malliciously deleted the thread (not knowing that it had been moved), or that a software error with the forum had caused it to be lost.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
rpdom
Posts: 11521
Joined: Sun May 06, 2012 5:17 am
Location: Essex, UK

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 8:30 pm

DavidS wrote:
DavidS wrote:
rpdom wrote:Looks fairly fixed width to me.
Not what it looks like here, unfortunately.
This is what it looks like here.
It looks like your browser isn't interpreting the html <code>...</code> tags to show as a fixed width font.

User avatar
scruss
Posts: 1305
Joined: Sat Jun 09, 2012 12:25 pm
Location: Toronto, ON
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 8:52 pm

DavidS wrote:Firstly it is not exactly a button, it is more of what other OS's call an Icon in this case (which is just one kind of Icon in RISC OS).
Your example program makes it behave like a button, so that's why I wrote the Tcl script that had the same effect: you click inside the image, the program quits.
And secondly the Sprite is 32 x 32 pixels, not 64 x 64, though in most modes having 2x2 ratio 32 pixels is 64 OS Units. This is obvious to those that know the target arch.
I'd say that this is entirely arbitrary, and having to remember a scale from bitmap size to screen size is arcane in the highest degree. So despite your (genuine, appreciated) best efforts to make BBC BASIC readable, the language and UI itself is full of idiosyncrasies that get in the way of getting stuff done.
‘Remember the Golden Rule of Selling: “Do not resort to violence.”’ — McGlashan.

User avatar
GavinW
Posts: 72
Joined: Tue Nov 01, 2011 8:11 pm
Location: UK
Contact: Website

Re: Readable Code Style, Review Requested.

Tue Nov 22, 2016 10:42 pm

Sorry! I misunderstood what it referred to in
what is it doing in RISC OS?
.

Back in Autumn of 2004 I wrote an article Why Lua is not BASIC in Frobnicate#22. Maybe I should bring it up to date with a wimp program for the comparison?
otium negare negotium vanum

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Wed Nov 23, 2016 3:15 am

scruss wrote:
DavidS wrote:Firstly it is not exactly a button, it is more of what other OS's call an Icon in this case (which is just one kind of Icon in RISC OS).
Your example program makes it behave like a button, so that's why I wrote the Tcl script that had the same effect: you click inside the image, the program quits.
Yes it does, in the same way that Picture Icons on most platforms are used (ok I do not handle double click, or menu click correctly in the example, though could easily do so).
And secondly the Sprite is 32 x 32 pixels, not 64 x 64, though in most modes having 2x2 ratio 32 pixels is 64 OS Units. This is obvious to those that know the target arch.
I'd say that this is entirely arbitrary, and having to remember a scale from bitmap size to screen size is arcane in the highest degree. So despite your (genuine, appreciated) best efforts to make BBC BASIC readable, the language and UI itself is full of idiosyncrasies that get in the way of getting stuff done.
Well it is a great solution to making screen modes of different aspect ratios display things that look the same.

The idea of OS Units for screen coords, is that it does not matter if you are running in a screen mode like 640x240 or 1280x1024 a window or object on the screen will still apear correct, as 640x240 is a 2:4 ratio for OS Units (that is 2 OS Units X per pixel, and 4 OS Units Y per pixel). So it is not so arcane, in fact it is simpler than most of the "modern" vector graphics methods used today (which RISC OS has also natively supported mode independant vector graphics since at least 1990, not sure about Arthur OS).


Though if it is not what you like, that is OK, and quite good to.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Wed Nov 23, 2016 3:16 am

GavinW wrote:Sorry! I misunderstood what it referred to in
what is it doing in RISC OS?
.

Back in Autumn of 2004 I wrote an article Why Lua is not BASIC in Frobnicate#22. Maybe I should bring it up to date with a wimp program for the comparison?
Yes please.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Wed Nov 23, 2016 3:27 am

stderr wrote:
DavidS wrote:Does not look like BASIC. Though does look most readable.
And now for a truly shocking bit of insight.
LOL. I thought Lua was supposed to be quite BASIC line, my bad.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

User avatar
DavidS
Posts: 3009
Joined: Thu Dec 15, 2011 6:39 am
Location: USA
Contact: Website

Re: Readable Code Style, Review Requested.

Wed Nov 23, 2016 3:32 am

What web browser are you using?
Its fixed width in Firefox.
I have no interest in using a browser as old as FireFox (I think the current version is 3.5, on RISC OS).

I primarily use NetSurf, the oe truely fast AND modern web browser for RISC OS.

I have not looked at code posts in these forums in any other web browser. It may be the font that is set as the fixed width font in NetSurf is not Fixed Width.
ARM BASIC: For the love of Simplicity, Fast Interpreted BASIC, and Assembly Language.
Always KISS Keep It Simple Silly.

jahboater
Posts: 1769
Joined: Wed Feb 04, 2015 6:38 pm

Re: Readable Code Style, Review Requested.

Wed Nov 23, 2016 10:49 am

DavidS wrote: I have no interest in using a browser as old as FireFox (I think the current version is 3.5, on RISC OS).
Yes, on my PC firefox is version 50.0!
DavidS wrote: as the fixed width font in NetSurf is not Fixed Width.
Then its not the forum at fault.
You just need to find a working browser.

Return to “RISCOS”

Who is online

Users browsing this forum: No registered users and 3 guests