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

Making readable modifyable code.

Tue Nov 22, 2016 4:29 pm

I know that I posted a similar topic the other day, though it dissapeared never to be heard from again, so I am posting this similar, though slightly different topic.

How do we write code that is readable to most others, and easy to modify?
This is a question that is plauging me at this time as I wish to start releasing some stuff I wrote, and want to make it easy to modify by others if they so wish.

As such I ask if these two examples are readable, as well as what thoughts people have on readability. First I will give the code of the two examples, written explicitly for the purpose of seeing what is readable for others.

First example in ARM BASIC for RISC OS:

Code: Select all

REM > !RunImage
REM * Simple program to answer the question of code readability.  The program
REM *   just places an Icon Sprite on the IconBar, and quits when the Icon is
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
Second example in ARM Assembly for RISC OS, assembles using ARM BASIC.

Code: Select all

REM > Source
REM Example to ask about readability.  Only creates an IconBar
REM Icon and waits until the Icon is clicked, then quits.
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$        ="!areadable":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.
_SizeOfStack%    = &00001000

DIM Buffer% 1024

FOR run% = 4 TO 6 STEP 2
P% = &8000
O% = Buffer%

 IF run% = 6 THEN
   TaskHandle% = EndOfCode% + _TempSize%
   IconHandle% = TaskHandle% + 4
   Stack% = (IconHandle% + _SizeOfStack%) AND &FFFFFF00
 ENDIF

[OPT run%
.Start% ;*********************************************************
  MOV R13,#Stack%             ;Setup Stack.
  STMFD R13!,{R0-R3,R14}

  LDR   R0,wimpVer%
  LDR   R1,taskMagic%
  ADR   R2,taskName%
  MOV   R3,#0
  SWI   "Wimp_Initialise"     ;Initialise WIMP for our task.
  STR   R0,TaskHandle%        ;Task handle is returned in R0.

  ADR   R1,Icon%
  SWI   "Wimp_CreateIcon"     ;Put Sprite Icon on IconBar.
  STR   R0,IconHandle%        ;Icon Handle returned in R0.

  BL    Poll%                 ;Call our poll loop.

  LDR   R0,TaskHandle%
  LDR   R1,taskMagic%
  SWI   "Wimp_CloseDown"      ;Release our task from the WIMP.

  LDMFD R13!,{R0-R3,R14}

.wimpVer%
  EQUD _WimpVer%
.taskMagic%
  EQUD _TaskMagic%
.taskName%
  EQUS _TaskName$+CHR$(0)
  ALIGN

.Poll% ;**********************************************************
  STMFD R13!,{R0-R3,R14}

  ADR   R1,TempWork%
.loop0%
  LDR   R0,pollFlags%
  SWI   "Wimp_Poll"           ;Call Wimp_Poll, returning poll
                              ; return reason in R0.

  CMP   R0,#6                 ;If poll reason is mouse click,
  LDREQ R3,[R1,#12]           ; and window is IconBar, we quit.
  CMNEQ R3,#2
  BEQ   quit%

  CMP   R0,#17
  CMPNE R0,#18                ;On Poll reason user message, with
  LDREQ R3,[R1,#16]           ; message being quit, we quit.
  CMPEQ R3,#0
  BEQ   quit%

  B     loop0%                ;Back around the poll loop.

.quit%
  LDMFD R13!,{R0-R3,R15}

.pollFlags%
  EQUD _PollFlags%


;*** Initialized Data. *******************************************
.TempWork%
.Icon%
  EQUD  -1                    ;Window handle of IconBar.
  EQUD   0                    ;Minimum X
  EQUD   0                    ;  and Y coords of our Icon.
  EQUD  64                    ;Maximum X and
  EQUD  64                    ;   Y coords of our Icon.
  EQUD  _IconFlagClick% OR _IconSprite%  ;Icon flags.
  EQUS  _AppIcon$+CHR$(0)     ;Name of sprite.
  ALIGN
.EndOfCode%
]
NEXT


SYS "OS_File", 10, "!RunImage", &FF8, , Buffer%, O%
So I ask what the thoghts are on the readability of both examples, both have been tested.

My personal thoughts on readability:
I personaly feel that following a few simple rules helps with readability. I have recently added 1 rule to these, thanks to peer review.

0 : Always make veriable names clear for there purpose.

1 : Always keep veriable names under 8 charactors in length.

2 : Comment in a clear and consise way what is being done.

3 : No more than one veriable declaration per line.

4 : Always clearly mark where functions/procedures/subroutines begin in a way that stands way out when scanning the code.

5 : Be consistant throughout a project.

6 : *NEW* Do not omit vowels to improve readability.

Now I did break rule 1 in these examples, and I did as well for rule 3. Though these are the result of modifications I made from existing peer review.

Please include your thoughts and suggestions.

THE ATTACHMENTS

The two attachments are the complete applications of the two examples above. As the examples are useless without there application dirrectory and the !Sprites22 file. Also for the fact that copy/paste from the foruum often breaks things.
Attachments
areadable.zip
ARM Assembly Example.
(2.71 KiB) Downloaded 83 times
Last edited by DavidS on Tue Nov 22, 2016 8:16 pm, edited 1 time in total.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

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

Re: Making readable modifyable code.

Tue Nov 22, 2016 4:31 pm

Second file would not attach to first post. So here it is.

File still refused to attach, sorry. So only the assembly example is attached to this thread :( .
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

DirkS
Posts: 9057
Joined: Tue Jun 19, 2012 9:46 pm
Location: Essex, UK

Re: Making readable modifyable code.

Tue Nov 22, 2016 6:39 pm

DavidS wrote:I know that I posted a similar topic the other day, though it dissapeared never to be heard from again
Disappeared? Do you mean this one: viewtopic.php?f=55&t=166228&p=1071627#p1070970 ?

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

Re: Making readable modifyable code.

Tue Nov 22, 2016 6:57 pm

DirkS wrote:
DavidS wrote:I know that I posted a similar topic the other day, though it dissapeared never to be heard from again
Disappeared? Do you mean this one: viewtopic.php?f=55&t=166228&p=1071627#p1070970 ?
Yes someone moved it on me. It was posted originally in "Programming.Other Languages", some mod moved it to RISC OS with out saying anything about it.

It does not belong in RISC OS, as it is not about any specific OS, though rather about coding style and readability.

I had just found it a few minutes ago.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

wildfire
Posts: 397
Joined: Sat Sep 03, 2016 10:39 am
Location: Dundee, Scotland

Re: Making readable modifyable code.

Tue Nov 22, 2016 7:45 pm

Why Rule 1, surely allowing variables to be greater than 8 chars in length would help?
DavidS wrote: It does not belong in RISC OS, as it is not about any specific OS, though rather about coding style and readability.

I had just found it a few minutes ago.
Erm, "View Your Posts"
Scotty never said "I canae give her any more Captain, She'll blow".
B'Elanna Torres however did say "Get the cheese to the sickbay" :?:

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

Re: Making readable modifyable code.

Tue Nov 22, 2016 8:15 pm

wildfire wrote:Why Rule 1, surely allowing variables to be greater than 8 chars in length would help?
It prevents over long veriable names that become unreadable as you often see now days. A name being to long is a bad thing.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

User avatar
DougieLawson
Posts: 33850
Joined: Sun Jun 16, 2013 11:19 pm
Location: Basingstoke, UK
Contact: Website

Re: Making readable modifyable code.

Tue Nov 22, 2016 9:38 pm

DavidS wrote:
DirkS wrote:
DavidS wrote:I know that I posted a similar topic the other day, though it dissapeared never to be heard from again
Disappeared? Do you mean this one: viewtopic.php?f=55&t=166228&p=1071627#p1070970 ?
Yes someone moved it on me. It was posted originally in "Programming.Other Languages", some mod moved it to RISC OS with out saying anything about it.

It does not belong in RISC OS, as it is not about any specific OS, though rather about coding style and readability.

I had just found it a few minutes ago.
All your RISCOS BASIC junk belongs in RISCOS, it's easier to ignore when it's over there. This thread belongs there too.
viewforum.php?f=55&mark=topics is a quick link to ignore all that uninteresting RISCOS junk.
Microprocessor, Raspberry Pi & Arduino Hacker
Mainframe database troubleshooter
MQTT Evangelist
Twitter: @DougieLawson

2012-18: 1B*5, 2B*2, B+, A+, Z, ZW, 3Bs*3, 3B+

Any DMs sent on Twitter will be answered next month.

User avatar
jojopi
Posts: 3041
Joined: Tue Oct 11, 2011 8:38 pm

Re: Making readable modifyable code.

Tue Nov 22, 2016 11:07 pm

DavidS wrote:ON ERROR PRINT "LINE : " + STR$(ERL) + " ERROR : " + REPORT$ : END
Why this? It seems both uglier and less efficient than the standard:

Code: Select all

REPORT:PRINT" at line ";ERL:END

asandford
Posts: 1999
Joined: Mon Dec 31, 2012 12:54 pm
Location: Waterlooville

Re: Making readable modifyable code.

Tue Nov 22, 2016 11:29 pm

DougieLawson wrote: All your RISCOS BASIC junk belongs in RISCOS, it's easier to ignore when it's over there. This thread belongs there too.
viewforum.php?f=55&mark=topics is a quick link to ignore all that uninteresting RISCOS junk.
It may be uninteresting and junk to you, but it might not be to others.

User avatar
DougieLawson
Posts: 33850
Joined: Sun Jun 16, 2013 11:19 pm
Location: Basingstoke, UK
Contact: Website

Re: Making readable modifyable code.

Tue Nov 22, 2016 11:43 pm

If it's in the right subforum it stops being a problem and stops being boring junk.

Because my first moves every day are to mark the RISCOS, graphics programming, gaming, graphics, sound & multimedia, media centres and bare metal forums as read (because those are the subjects I don't have any interest in and it's a hard enough job tracking 150 new posts per day).
Microprocessor, Raspberry Pi & Arduino Hacker
Mainframe database troubleshooter
MQTT Evangelist
Twitter: @DougieLawson

2012-18: 1B*5, 2B*2, B+, A+, Z, ZW, 3Bs*3, 3B+

Any DMs sent on Twitter will be answered next month.

asandford
Posts: 1999
Joined: Mon Dec 31, 2012 12:54 pm
Location: Waterlooville

Re: Making readable modifyable code.

Tue Nov 22, 2016 11:58 pm

DougieLawson wrote:If it's in the right subforum it stops being a problem and stops being boring junk.

Because my first moves every day are to mark the RISCOS, graphics programming, gaming, graphics, sound & multimedia, media centres and bare metal forums as read (because those are the subjects I don't have any interest in and it's a hard enough job tracking 150 new posts per day).
Well, it's not all about you...

And boring junk, in your very humble opinion, may well be interesting to others. If you find this thread of no interest, then move along to one that does, no need to post nasty comments.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:00 am

DougieLawson wrote:If it's in the right subforum it stops being a problem and stops being boring junk.

Because my first moves every day are to mark the RISC OS, graphics programming, gaming, graphics, sound & multimedia, media centres and bare metal forums as read (because those are the subjects I don't have any interest in and it's a hard enough job tracking 150 new posts per day).
This thread is not about RISC OS. Just because I use RISC OS as an example (because it makes a short easy to read example program, that most can understand), does not make it OS specific.

Last time I checked people write and share code Linux, Plan9, BSD, and Windows 10 IoT also, not just RISC OS. As such the question of making readable code seems to be universal, and NOT OS SPECIFIC.

Sorry if you feel that only people programming for RISC OS need to make readable code.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:08 am

asandford wrote:And boring junk, in your very humble opinion, may well be interesting to others. If you find this thread of no interest, then move along to one that does,
While I'm not a fan of moving threads around, how is a thread on how to write readable riscos basic not a thread that should be in riscos? If that doesn't belong there, nothing does.

The point of having different forums is to segregate materials so people can more easily find what they are looking for, and yes, avoid things they aren't interested in. Furthermore, clearly, much of this more broadly posted material contains a proselytising tone which is certainly the real motivation.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:19 am

stderr wrote:
asandford wrote:And boring junk, in your very humble opinion, may well be interesting to others. If you find this thread of no interest, then move along to one that does,
While I'm not a fan of moving threads around, how is a thread on how to write readable riscos basic not a thread that should be in riscos? If that doesn't belong there, nothing does.

The point of having different forums is to segregate materials so people can more easily find what they are looking for, and yes, avoid things they aren't interested in. Furthermore, clearly, much of this more broadly posted material contains a proselytising tone which is certainly the real motivation.
Firstly how is BASIC equal to Assembly?

Second To quote myself:
This thread is not about RISC OS. Just because I use RISC OS as an example (because it makes a short easy to read example program, that most can understand), does not make it OS specific.

Last time I checked people write and share code Linux, Plan9, BSD, and Windows 10 IoT also, not just RISC OS. As such the question of making readable code seems to be universal, and NOT OS SPECIFIC.

Sorry if you feel that only people programming for RISC OS need to make readable code.
So how do you see readable program source as a RISC OS only problem????

Or for that matter how is it a langage specific problem?
Last edited by DavidS on Wed Nov 23, 2016 3:46 am, edited 1 time in total.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:23 am

OK, getting back on topic:
jojopi wrote:
DavidS wrote:ON ERROR PRINT "LINE : " + STR$(ERL) + " ERROR : " + REPORT$ : END
Why this? It seems both uglier and less efficient than the standard:

Code: Select all

REPORT:PRINT" at line ";ERL:END
To be honest, I have never used REPORT, even after 27+ years of BBC BASIC on RISC OS.

Thank you for that.
26-Bit R15 to 32-bit. 16-bit addressing to 24-bit. ARM and 65xx two CPU's that continue on, and are better than ever. Assembly Language forever :) .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 6:22 am

DavidS wrote:How do we write code that is readable to most others, and easy to modify?
If others will be reading and modifying the code, the comments need to explain what is not obvious from the code itself while at the same time not explaining things that are are obvious from the code. The comments should consist of correctly spelled, capitalized and punctuated English sentences. Where appropriate, citations to reference books, other programs and journal articles on which the code was based should also be included in the comments. In my opinion readability is also enhanced when each block of code, function or subroutine can be visually audited on a reasonable sized screen without having to page up or down.

Heater
Posts: 9841
Joined: Tue Jul 17, 2012 3:02 pm

Re: Making readable modifyable code.

Wed Nov 23, 2016 11:06 am

On readability:

Clunky things like "REM" for comments are ugly. A simple // or # is cleaner and more legible.

Keywords in upper case is an eyesore.

I can't stand for variable and other names to start with "_". Or even have "_" in them.

What's with the "%" on the end of names? That kind of thing kills readability.

Things like PROC and ENDPROC are ugly. Why not use simple braces?

Arbitrarily limiting yourself to 8 character names is going to result in a lot of unreadable, meaningless names.

I hate to see the work that is done conditionally on the same line as the condition.

On the location of this thread:

I don't known where it belongs. My observation is that a lot of what is good style and readability is language dependent. Not all but a lot. Languages have programmers, programmers are a community with a culture. Over time that culture evolves common styles and idioms. The community develops an expectation of what they like to see in code.

For example, the way I format Javascript is very different than the way I format C/C++. Even though there is a lot of superficially commonality in the syntax and structure of the languages. Why? Because I'm blending into, influenced by, different communities when working in JS and C. Communities with different expectations of "good practice".

Surely the community of BASIC programmers on RISC OS have developed their own cultural style and expectations after all the decades? No need to discuss it here.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 1:40 pm

Heater wrote:On readability:

Clunky things like "REM" for comments are ugly. A simple // or # is cleaner and more legible.

Keywords in upper case is an eyesore.

I can't stand for variable and other names to start with "_". Or even have "_" in them.

What's with the "%" on the end of names? That kind of thing kills readability.

Things like PROC and ENDPROC are ugly. Why not use simple braces?

Arbitrarily limiting yourself to 8 character names is going to result in a lot of unreadable, meaningless names.

I hate to see the work that is done conditionally on the same line as the condition.
Much of what you are complaining about is intrinsic to the BASIC language. For example % indicates that the variable is an integer. If you don't like all this ancient rubbish, then use a modern language. However:
I hate to see the work that is done conditionally on the same line as the condition.
yes++ its dreadful.
Keywords in upper case is an eyesore.
agreed.
I can't stand for variable and other names to start with "_".
Agreed - appalling.
Or even have "_" in them.
Now here I strongly disagree. If you wrote a letter to your mother, would you remove all the spaces and capitalise every single word? No. In algol you could have spaces within variable names, the best we can do in C is the '_', but its far far more readable than removing the gaps from between words. Unless you are entering a code obfuscation contest!
Last edited by jahboater on Wed Nov 23, 2016 2:44 pm, edited 1 time in total.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 1:53 pm

I may be out of step here, but I much prefer camelCase for variable names. To my eyes "_" are easily mistaken for spaces when scanning code, and to me spaces are the separators between symbols.

PeterO
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
DougieLawson
Posts: 33850
Joined: Sun Jun 16, 2013 11:19 pm
Location: Basingstoke, UK
Contact: Website

Re: Making readable modifyable code.

Wed Nov 23, 2016 2:17 pm

DavidS wrote:
Sorry if you feel that only people programming for RISC OS need to make readable code.
Don't be an idiot. If you want to discuss readable code work with a commonly used language, not some junk that resides in a backwater where nobody but you uses it.

Use python, there's a fantastic example of a language that needs some readability improvement because it's syntactically crippled before you write your first line.

Or stick with C which doesn't carry any baggage other than where you put your braces.

I agree with Peter, camelCase may be ugly but at least it's non-ambiguous. I quite like COBOL with all-of-its-wasted-hypens.
Microprocessor, Raspberry Pi & Arduino Hacker
Mainframe database troubleshooter
MQTT Evangelist
Twitter: @DougieLawson

2012-18: 1B*5, 2B*2, B+, A+, Z, ZW, 3Bs*3, 3B+

Any DMs sent on Twitter will be answered next month.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 2:24 pm

PeterO wrote:I may be out of step here, but I much prefer camelCase for variable names. To my eyes "_" are easily mistaken for spaces when scanning code, and to me spaces are the separators between symbols.

PeterO
Ok, fair point, I had not thought about that.
My eyesight isn’t great, but I am short sighted so '_' is not a problem!

Heater
Posts: 9841
Joined: Tue Jul 17, 2012 3:02 pm

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:07 pm

jahboater,
Much of what you are complaining about is intrinsic to the BASIC language.
Yeah, I know. I was being a bit playfully provocative there :)
If you don't like all this ancient rubbish, then use a modern language.
Sure do. Since 1974!
If you wrote a letter to your mother, would you remove all the spaces and capitalise very single word?
Certainly not. And that's not what I was suggesting.

In English, at least, we have words that are the names of things. Be they actual things (nouns), or more abstract things like actions (verbs) or descriptions (adjectives). It is very common for these words to be run together to create new names for things. For example "seahorse", "bobcat", "automobile", "greybeard". Then we have a bunch of other words that seem to work like operators: "if", "then", "else", "but", "and", "or", "as", "is", "when".... We do not tend to run the words together with others.

Some languages take this a lot further. In Finnish you might see "autokirjakauppa" which is "Car Book Store". Or worse, how about: "epäjärjestelmällistyttämättömyydellänsäkään" which seems to mean "even with its quality of not being possible to be made irrational."

In Welsh we have: "Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch". The meaning of which I will let you google for.

So, it seems quite natural to me that people world run words together in creating variable and other names in programming languages. CamelCase makes it very readable. Using underscores make names overly long and are unnecessary.

I can see underscore just fine (unless the font in use is broken) which is why I think they are ugly :)

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:26 pm

Heater wrote: It is very common for these words to be run together to create new names for things. For example "seahorse", "bobcat", "automobile", "greybeard".
But then they become a new single word?
Heater wrote: Some languages take this a lot further. In Finnish you might see "autokirjakauppa" which is "Car Book Store". Or worse, how about: "epäjärjestelmällistyttämättömyydellänsäkään" which seems to mean "even with its quality of not being possible to be made irrational."

In Welsh we have: "Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch". The meaning of which I will let you google for.
Its a place name from memory, likely made up to get in the record books.

These examples exemplify how unreadable joined up words can be, an argument against camelCase!

"car book store" could be either "car_book_store" or "carBookStore" - so which is the closest to English? and yet no longer than the original English.

All down to personal taste really. :)

Heater
Posts: 9841
Joined: Tue Jul 17, 2012 3:02 pm

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:43 pm

jahboater,
But then they become a new single word?
Exactly. Somebody had to but "earth" and "quake" together for the fist time to get "earthquake". When you are writing code you are constantly creating new names for things. Why not follow the natural language trend? Why do something weird instead?
These examples exemplify how unreadable joined up words can be, an argument against camelCase!
OK, let's ignore the foreign languages. In English things tend to be clear enough. Do they not?
(Most of Finnish is not so extreme mind).
All down to personal taste really.
Turns out that way. People reject camel case epäjärjestelmällistyttämättömyydellänsäkään. If you see what I mean :)

hippy
Posts: 3789
Joined: Fri Sep 09, 2011 10:34 pm
Location: UK

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:47 pm

In my mind, "readability" is a rather subjective issue, whether one prefers camelCase to ALL_CAPS and underscores and whether they can be excused, tolerated or accepted as having semantic purpose when used to signify different things; say variables and constants.

I think everyone will find what they prefer more readable than what goes against that preference. That doesn't necessarily mean one preference is wrong and another is right but it is best to adopt to the style the reader likely expects.

The real issue is perhaps not "readability" but "clarity" and "understandability" and that will depend on the target audience the source code is intended for and the context it is supplied in.

In particular there are two distinct aspects of any program; what it is doing, and how it is doing that.

For me, I don't have any real comprehension of what "is this code readable?" actually means. And "is this code clear and understandable" rests upon; clear and understandable to who ?

Return to “General programming discussion”

Who is online

Users browsing this forum: Lonewolff and 8 guests