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

Re: Making readable modifyable code.

Wed Nov 23, 2016 3:54 pm

To me it seems this whole thread, and several like it , serve only one purpose: To distract us from noticing that the OP never actually seems to write any code !
PeterO
Discoverer of the PI2 XENON DEATH FLASH!
Interests: C,Python,PIC,Electronics,Ham Radio (G0DZB),1960s British Computers.
"The primary requirement (as we've always seen in your examples) is that the code is readable. " Dougie Lawson

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 4:11 pm

Each person has a fixed amount of mental processing they can do.
When reading large amounts of code, there are two parts. 1) the reading of the code and 2) the understanding of what it really does and the analysis of where the bug lies.

1) always requires some mental parsing. The parsing effort is subtracted from your fixed mental processing limit. What remains deals with (2).

The degree of mental parsing for (1) should be the absolute minimum so as to leave more available for (2).

I think aircraft pilots call this concept the "cockpit workload", the more mental effort required for routine scanning of instruments etc, the less there is available for dealing with real problems.

Obvious I guess. But readability is important.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 4:21 pm

PeterO,
...To distract us from noticing that the OP never actually seems to write any code !
Hmmm...

Perhaps we should all get off the forum for a month. Take time out to create something wonderful and fun. Then come back and compare our work.

Then we can all rip into each others code styles meaningfully :)
Memory in C++ is a leaky abstraction .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 4:26 pm

Heater wrote:Then we can all rip into each others code styles meaningfully :)
In essence that's what it seems to come down to; is a particular coding style readable or not.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 4:51 pm

Heater wrote:On readability:

Clunky things like "REM" for comments are ugly. A simple // or # is cleaner and more legible.
While I agree the language I chose for the examples is the limit here. In assembly I use ; comments, in QucikBASIC/FreeBASIC I use ' for comments, in C I use both /**/ and // comments.
Keywords in upper case is an eyesore.
Matter of opinion?

While it is a bit unsightly, it definitely destinghishes keywords from everything else. And it is better than the all upercase defines often used in modern systems (now that is a real eyesore).

That said in other versions of BASIC I use lowercase keywords, ARM BASIC is upercase only.
I can't stand for variable and other names to start with "_". Or even have "_" in them.
Thank you. I am glad to hear that, I do not like underscores either, I used to have no underscores as one of my rules, and will reimplement that rule. Thank you.
What's with the "%" on the end of names? That kind of thing kills readability.
It is something I like about ARM BASIC, as well as some other BASIC versions. Types are done by a postfix on the name, with no postfix being real, % being 32-bit integer, and $ being a string of characters.
Things like PROC and ENDPROC are ugly. Why not use simple braces?
In languages that use braces I do use braces, the example language I chose imposes this limit.
Arbitrarily limiting yourself to 8 character names is going to result in a lot of unreadable, meaningless names.
Matter of opinion.

I will allow myself up to 12 characters if absolutely needed for readability.
[/quote]
I hate to see the work that is done conditionally on the same line as the condition.
[/quote]
I can understand that.
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.
While the example is in ARM BASIC, it is about all languages.

I chose the language of the example as it it has more difficulties in making readable code than most other languages. Thus I am hoping that the lessons of this thread can be done such as to apply to ALL procedural programming languges.

Also you will note that one example is in ARM Assembler. That is also do to the level of readability and difficulty for some.
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 4:53 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
I agree with that completely.
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 5:04 pm

hippy wrote: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.
+1.

I think that is a big part of the issue.

I am asking this question here because it is useful to see the input of many, and use that to build a guidline that can be used in and is good for the originating programmer, though is still able to produce good code that is easy to read for others.
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 ?
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 5:08 pm

PeterO wrote:To me it seems this whole thread, and several like it , serve only one purpose: To distract us from noticing that the OP never actually seems to write any code !
PeterO
Ah nice to see you are standing outside my window watching me. Oh; you are not, if you were you would see that I spend 80% of my time writing code.

I thing you mean I rarely share code, that is a way different thing all together. Though I always share it with someone, just rarely publicly.
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 5:11 pm

jahboater wrote:Each person has a fixed amount of mental processing they can do.
When reading large amounts of code, there are two parts. 1) the reading of the code and 2) the understanding of what it really does and the analysis of where the bug lies.

1) always requires some mental parsing. The parsing effort is subtracted from your fixed mental processing limit. What remains deals with (2).

The degree of mental parsing for (1) should be the absolute minimum so as to leave more available for (2).

I think aircraft pilots call this concept the "cockpit workload", the more mental effort required for routine scanning of instruments etc, the less there is available for dealing with real problems.

Obvious I guess. But readability is important.
Agreed, and that is why I write things the way I do, because FOR ME coming back later it is easy to parse, for others not so much.

I am attempting to find a compromise that makes my code clear to others, while still remaining clear to me.
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 5:16 pm

Heater wrote:PeterO,
...To distract us from noticing that the OP never actually seems to write any code !
Hmmm...

Perhaps we should all get off the forum for a month. Take time out to create something wonderful and fun. Then come back and compare our work.

Then we can all rip into each others code styles meaningfully :)
I like that idea. Though a month may be a bit long (most fun projects are less than 3000 lines of code and take a week or two to complete).

Do you have a simple guidline for the kind of project in mind, or just something random?
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 5:49 pm

DavidS wrote:Agreed, and that is why I write things the way I do, because FOR ME coming back later it is easy to parse, for others not so much.

I am attempting to find a compromise that makes my code clear to others, while still remaining clear to me.
The attempt by Bourne to make the C source code for the Unix shell more readable is interesting. Another example is the notation for making the types of variables visible that among other places was promoted by Microsoft in early Windows code examples. The dollar and percent signs in BASIC are the same idea. While neither of these ideas have proven useful enough to be generally used, each was useful for a certain audience at a certain time.

As with all writing, the rule write for your audience applies. If you are writing code that will be read by scientists that are expert Fortran programmers, write in Fortran. If for Unix greybeards and most open source projects write in C. If for web developers use JavaScript and NodeJS. If programmers working on legacy banking and accounting systems write in COBOL. If the audience is computer science students write in pseudocode. If for Pi enthusiasts write in Python.

Of course you also have to know the language well to write in it clearly. The observation quoted above that the code should be understandable to the author is an important one.

There is an audience for each language. If you want to write something that is readable by a particular audience, writing in the language they are familiar with will increase readability of the code significantly.

amatbrewer
Posts: 6
Joined: Fri Aug 26, 2016 4:45 pm

Re: Making readable modifyable code.

Wed Nov 23, 2016 6:18 pm

I am constantly amazed at how many ‘rabbit holes’ some postings go down (which can be really fun) and how often they involve attacks on OP or other posters (which is not fun)…sigh…
I would say there are lots of really good ideas and suggestions here and while I may not agree with all of them and/or some may not work for me, if they are working for you than they are ‘right’. As has already been mentioned, “readable” is highly subjective. Everything here should be seen as nothing more than suggestions to take or leave as one sees fit.

My $.02…
While I don’t always do it, I am a proponent in readable code. Both for myself later and for others who may end up reading it. How I achieve that is constantly evolving. I think one major key is consistency through a program. Once I start using a method I try to maintain it throughout the code.
Commenting as much as may be necessary to explain non obvious code is important. This is highly variable with the content and intended audience. (I am really bad at this, but am trying to get better).
I personally like ‘camelCase’ but unless I misread the posts, I think a point was missed in the ‘simply making a new word’ discussion. I like it to help identify where/how a variable fits into my code. For example; LcFiftithPerc to identify that this is the 50 percentile of the LC dataset.
I limit the use of all caps for constants. (an old habit I picked up when I first started programming back in the early 80’s)
I use underscores sometimes when it seems to be appropriate.
I also like to group as many variable declarations together as early in the code as possible (e.g. top of program and/or top of function declaration) to make them easy to find.
I try to use white space effectively. Obviously some languages use white space while others ignore it. But I find space between sections of code and indents make for much more readable code. As does breaking up long lines of code (if possible) into logical parts either functionally by actually breaking them down into separate statements, or visually by adding line breaks (if the language allows that).

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 6:29 pm

amatbrewer wrote: I personally like ‘camelCase’ but unless I misread the posts, I think a point was missed in the ‘simply making a new word’ discussion. I like it to help identify where/how a variable fits into my code. For example; LcFiftithPerc to identify that this is the 50 percentile of the LC dataset.
The point was not missed, just the discussion moved on.
I don't think readable code is the place to "invent" new words.
Surely its quicker to read and understand if the language consists of words you know and are familiar with?

The variable names must be pronounceable too.
Trying to read and mentally parse stuff like "LcFiftithPerc" is obviously slow.
Perhaps if the code is clearly dealing with the LC dataset, then there is no point in replicating that in the name, a slight improvement to "FiftithPerc".
Finally, what on earth does "Fiftith" mean? what's wrong with "Fiftieth"?
We now have "FiftiethPerc".

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 6:47 pm

(The fiftieth percentile is called the median.)

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 6:49 pm

jojopi wrote:(The fiftieth percentile is called the median.)
Thankyou!
Lets just call our variable "median" - I like that.
So so much easier to read.

amatbrewer
Posts: 6
Joined: Fri Aug 26, 2016 4:45 pm

Re: Making readable modifyable code.

Wed Nov 23, 2016 7:16 pm

jahboater wrote:
jojopi wrote:(The fiftieth percentile is called the median.)
Thankyou!
Lets just call our variable "median" - I like that.
I would agree, and in many cases "median" would make for more readable code. So maybe that was not the best example. In the particular (R) code I pulled that from, it is using various percentile points from within the data set as part of a rather complex filter to identify the desired data for later processing. So in this case the particular naming is entirely relevant to myself and my peers who will be using the code. While using 'median' would have unnecessarily isolated this from the other percentile variables used, making it less readable (to the intended audience). Hence the point others have made about readability being subjective and pliable.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 8:25 pm

amatbrewer wrote:
jahboater wrote:
jojopi wrote:(The fiftieth percentile is called the median.)
Thankyou!
Lets just call our variable "median" - I like that.
I would agree, and in many cases "median" would make for more readable code. So maybe that was not the best example. In the particular (R) code I pulled that from, it is using various percentile points from within the data set as part of a rather complex filter to identify the desired data for later processing. So in this case the particular naming is entirely relevant to myself and my peers who will be using the code. While using 'median' would have unnecessarily isolated this from the other percentile variables used, making it less readable (to the intended audience). Hence the point others have made about readability being subjective and pliable.
You can't use median as a variable in R because median is the name of a built-in function. However, misspelling fiftieth does not seem like a good idea. Like it or not, the readability of code with obvious misspellings is diminished because potential readers may assume the code is wrong in other ways and, therefore, not take much effort to read it.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 9:18 pm

Many good sugestions on this thread, I think I may be able to make a decent comprimise for the release versions of some code I have waiting to go onto my site.

Obviously I will not be able to update everything before uploading, though at least I will be able to get things clearer before uploading.

Also I still say the following makes a decent view. Except the leave the forums part (would rather to just avoid the programming sections for that period of time).
DavidS wrote:
Heater wrote:PeterO,
...To distract us from noticing that the OP never actually seems to write any code !
Hmmm...

Perhaps we should all get off the forum for a month. Take time out to create something wonderful and fun. Then come back and compare our work.

Then we can all rip into each others code styles meaningfully :)
I like that idea. Though a month may be a bit long (most fun projects are less than 3000 lines of code and take a week or two to complete).

Do you have a simple guidline for the kind of project in mind, or just something random?
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 9:28 pm

As to the recomendation from Heater:
I suggest that for the purpose of what he recomends (writing a fun program to show coding style, that is complete) a few guidlines.

The guidelines that make since for me (for the purpose at hand) are:
  • Must be a multi file project.
  • Must be able to target ARM Linux (I think everyone here uses ARM Linux).
  • Must use some form of graphical output.
  • Must be interactive.
  • Must be writen in what ever compiled/assembled language and coding style the author prefers.
  • Must be small enough to include in a forum attachment (within a zip) including source and binary.
  • Must not recycle code from other projects (except for in binary libraries used).
These I think would be non-restrictive guidlines that would fill the bill of a program that is long enough to use as an example of different coding styles (in many programming languages by time everyone chips in), inluding the way people manage multiple source file projects.

Does this seem acceptable to all interested in taking Heater up on his suggestion (including Heater)?
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 9:38 pm

ejolson,
You can't use median as a variable in R because median is the name of a built-in function.
You mean R has made the same mistake as many languages before. Building functions in to the very language syntax rather than keeping them separate from the language itself.

A recent example is the change in Python from "print" as a language keyword to "print" as a library thing.
Memory in C++ is a leaky abstraction .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 9:47 pm

DavidS,
Does this seem acceptable to all interested in taking Heater up on his suggestion (including Heater)?
Not really.

My suggestion was to actually do something. Anything. Anyhow. Whatever shakes your tree.

I don't care how many files it takes. I would be happier if the result was interesting/useful to users of any platform not just ARM. GUI is optional, could be a robot control thing or whatever. Never mind the forum attachment, we have github, bitbucket, etc, through which we can share code. Recycling code from others is quite OK if it helps get the job done (Licensing allowing of course).

Go forth and hack!
Memory in C++ is a leaky abstraction .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 9:55 pm

Heater wrote: Go forth and hack!
I have not programmed in forth for over 30 years, cant remember much.

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 10:24 pm

jahboater wrote:
Heater wrote: Go forth and hack!
I have not programmed in forth for over 30 years, cant remember much.
+1

:)

LOL
RPi = The best ARM based RISC OS computer around
More than 95% of posts made from RISC OS on RPi 1B/1B+ computers. Most of the rest from RISC OS on RPi 2B/3B/3B+ computers

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 10:27 pm

jahboater,
I have not programmed in forth for over 30 years, cant remember much.
Ha! Oh shoot. That is not what I had in mind :)

Still, 30 years later many people are doing amazing things on micro-controllers in Forth.

I never did get the hang of it. It's such a primitive high level language and impossible for me to read. Easier to use assembler!

Still, whatever shakes your tree.
Memory in C++ is a leaky abstraction .

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

Re: Making readable modifyable code.

Wed Nov 23, 2016 10:42 pm

Heater wrote:jahboater,
I have not programmed in forth for over 30 years, cant remember much.
Ha! Oh shoot. That is not what I had in mind :)

Still, 30 years later many people are doing amazing things on micro-controllers in Forth.

I never did get the hang of it. It's such a primitive high level language and impossible for me to read. Easier to use assembler!

Still, whatever shakes your tree.
"Go forth and hack!" And sorry, I have never programmed in Go at all! :?

I had a machine similar to the sinclair ZX80 that used Forth instead of BASIC.
It was called the Jupiter Ace. Good grief just googled it:-
http://www.ebay.co.uk/itm/like/11220734 ... 505&crdt=0
I think I paid about £30 for it, and probably still have it somewhere.

Forth was its main attraction. It was very very fast compared to the BASIC programmed z80 machines of its day.

Return to “General programming discussion”