Blog article on some programming guidelines

Off-Topic
#1

I have posted some coding style guidelines (which other programmers on Twitter generally approved of) recently:

http://blog.tempel.org/2019/06/tts-generic-programming-guidelines.html

Enjoy.

#2

I disagree about booleans BUT …

I do like [quote]Document what you want to achieve in your code[/quote]
Quite often I will actually write the pseudo code for the method first then fill in details between the lines of pseudo code
Basically writing the docs FIRST

#3

Someone off list asked me why I disagree about that boolean style
My #1 reason is that in order to use it effectively you rely on well named booleans and, to be honest, not everyone is good at picking names. Or they are in another language you can’t read or make sense of - I’m working in some code written predominantly in German and also rewrote some written in Chinese :slight_smile:

Trying to read that as “English” is a total fail

But even in German or Chinese a line like

  if einigeWirklichSchrecklicheVariablennamen = true then

is absolutely unambiguous regardless of what that variable name means

#4

In regards to Boolean… .I must agree with Norman.

Another problem with leaving out the TRUE/FALSE is that not all languages support that syntax … thus creating a “bad habit” that might bite you in the backside later in life.

#5

WHAT?!? Boolean expressions are one of the most fundamental concepts in every programming language since the 70s. Heck, even shell scripts know the concept. Just tell me one language that doesn’t do that. Please don’t mention APL or something that’s older than us all :slight_smile:

I see a lot of Xojo programmers prefer the “… = true” syntax, but not doing that is something you can get used to. For newbies, that “=true” part its not helping, as it is against the natural language, and also clouding the understanding of boolean expressions. Just seeing this comment from Dave already makes my point: Dave does not seem understand the concept of a bool expression.

Because, the funny thing is that if you believe you have to add “= true” to a boolean expression, then you ignore the fact that that construct ALSO becomes a boolean expression. So, with that logic, you’d have to add another “=true” to it:

[code]dim thisIsIt as boolean

if thisIsIt then … // a bool expr without any nonsense, the way I recommend it
if thisIsIt = true then … // also a bool expr
if (thisIsIt = true) = true then … // also a bool expr
if ((thisIsIt = true) = true) = true then … // also a bool expr[/code]

How far to you want to go with this nonsense, then?

Here’s another example of using a boolean expression efficiently, avoiding writing unnecessarily long code:

If Me.ListIndex = -1 Then // and why not: If (Me.ListIndex = -1) = True Then ConnectButton.Enabled = False Else ConnectButton.Enabled = True End If

That could have been a one-liner:

ConnectButton.Enabled = Me.ListIndex >= 0

Once an algorithm is coded, it’s not relevant any more what type a variable is (the compiler takes care of ensuring the type is fitting). All that’s important is that it’s easy to comprehend. That’s why I am also strongly against including type into in the names of variables. Bkeeney’s code does that a lot, for instance, and I find it very difficult to read.

Mind you - when I presented my guidelines first to the experienced programmer followers I have on Twitter (and who mainly program in ObjC, Swift, C etc.), none of them disagreed with the boolean thing. It’s mainly a Xojo thing, not a universal “good idea”.

And then there’s the heaps of badly written example code that comes with Xojo: Much of it violates many of my guidelines - that’s actually part of why I wrote them, because my students started writing such bad code, and when I told them how to improve it, I eventually found out that they started out with these examples. I find that a terrible thing that a development system guided towards beginning programmers comes with such bad badly written code for guidance.

One of these bad examples: The often-needed “how do I read a directory recursively” example “FileBrowser.xojo_binary_project”. It’s not only full of repetition, it also has several bugs, such as not checking for nil results, using Item() instead of TrueItem() (the latter can result in endless recursion), needless use of GetRelative() (that’s for storing folder refs across runs of the program, not re-identifying items while the app is still running), not using LastIndex but counting the rows on its own, idiotic way of checking for today. There’s hardly a single line that’s okay. It’s just horrible. And I am afraid that many beginners base their code on this example and get started with all these bad habits from the start. My students did, and I embarrassed that I first chided them for writing such bad code only to learn that it was Xojo’s “exemplary” code and not theirs.

#6

I have to agree with Thomas on the Xojo examples as provided. While a “seasoned” programmer can figure out what’s going on and work through the inconsistencies, a complete new comer will be confused.

In my Summer session mentoring, I always removed the Examples folder and used specific apps that provided a more consistent group of ideas - naming variables being one of them. One of these students from 2016 just started his Comp-Sci classes and used these ideas in his first assignment. The professor pushed him forward 2 classes because he already had a better idea about code design than a number of the 2nd or 3rd year students that they normally see.

Now, if I could just get my own team to adhere to such design ideas :slight_smile:

#7

[quote=444298:@Norman Palardy]Quite often I will actually write the pseudo code for the method first then fill in details between the lines of pseudo code
Basically writing the docs FIRST[/quote]
When I coded in (Turbo) Pascal, and in Modula-2, where you’d also have something like a header file (it was declaring your public functions and properties for sharing with other code files), I learned to make it a habit to always write these header files first, and I’d document their behavior right in there, too. Later, I saw the same happen in C header files (just look nowadays at Apple’s header files - they have all the docs right in there). It’s the same thing that Norman suggests, just even more organized (we can’t do that in Xojo that way because we don’t have separate declaration & documentation parts for methods).

And thank you, @Tim Jones , for that example of making an effort of teaching a good coding style :slight_smile:

#8

In fact, we’ve never discussed this in this manner (that I could find), so I looked for a feedback report. While there have been a few aimed at fixing specific examples, there’s never been a request to refactor them all for up to date code and consistency.

I’ve created a feature request: feedback://showreport?report_id=56307

#9

Good move. And, with the agreement that Xojo requires anyone submitting an example has to agree with, Xojo takes ownership of the code and thus has the right to make changes to it as they seem fit. I used to dislike that requirement, but in regards to making the examples better, it would be an advantage now. Only, why did they require this if they hadn’t already tought of improving the examples, then? Oh well, shortage of resources, as usual, I guess :slight_smile:

Regardless, it would be nice if Xojo could publish some coding standards themselves, similar to what I wrote, and then ask that anyone submitting examples would adhere to those standards.

Oh, did I mention that even the recent posts on some programming examples on the Xojo blog were not good in that regard, either (even had blatant bugs, IIRC) ? I mean, Xojo attempts to make programming easy for beginners, yet many of its examples come from similarly inexperienced programmers, and there’s no one who oversees this and gives guidance. It’s not healthy.

#10