Please add comments to example code

[Steve-h]

We are all very grateful to all those who post examples and small bits of code but please could I ask that you add plenty of comments, far more than you would think were required.

What is completely obvious to you is a complete mystery to others. Also whatever your code is demonstrating please avoid clever and complicated ways of doing stuff unless that is what the actual example is. It just makes it more difficult for beginners (me) to understand.

 

[AnandGupta]

but please could I ask that you add plenty of comments, far more than you would think were required.

It is difficult for an expert to determine how many comments will suffice a beginner. So he/she always encourages to 'ask question by staring a thread'.

What is completely obvious to you is a complete mystery to others

This is same as I look bewildered to what my wife just said. Mystery.
Jokes apart, do you remember your school days when the teacher explained the obvious and all was mystery for everyone.
An expert will 'always see the obvious'. Again here 'ask question by staring a thread'.

Also whatever your code is demonstrating please avoid clever and complicated ways of doing stuff unless that is what the actual example is. It just makes it more difficult for beginners (me) to understand.

And how the ten years experienced developer would understand which code of his/her is complicated in other's eye ?
It goes without saying, 'put your query' and believe me most experienced programmers here, stumble on the rocky place called Android.

But you have the friends here who will help you out with solved examples many times.

 

[emexes]

add plenty of comments

and verbose, relevant variable names (says the guy still using Fortran I, J, K for loops)

 

[agraham]

(says the guy still using Fortran I, J, K for loops)

Who doesn't?

 

[Star-Dust]

(says the guy still using Fortran I, J, K for loops)

Who doesn't?

I don't do it, I use Pascal I,J,K for loops

 

[Marvel]

Sometimes I go back to my code and don't even understand why I wrote it that way
I get your point though, but the forum is always ready to help on any questions you have.

 

[Star-Dust]

Sometimes I go back to my code and don't even understand why I wrote it that way
I get your point though, but the forum is always ready to help on any questions you have.

I always don't understand what I wrote, but if it works I use it anyway

 

[Marvel]

I always don't understand what I wrote, but if it works I use it anyway

 

[aeric]

We are all very grateful to all those who post examples and small bits of code but please could I ask that you add plenty of comments, far more than you would think were required.

What is completely obvious to you is a complete mystery to others. Also whatever your code is demonstrating please avoid clever and complicated ways of doing stuff unless that is what the actual example is. It just makes it more difficult for beginners (me) to understand.

Can you give some examples of “difficult to understand examples”?

Some examples will give you answer (or make you understand) once you run it and see the results.

 

[Star-Dust]

Perhaps you think your I, J, K are from Pascal but in reality you are an accidental historian :

Speedcoding --> FORTRAN --> Algol --> Pascal

Algol also begat C indirectly: Algol --> CPL --> BCPL --> B --> C

I think BASIC was FORTRAN, but leaning more towards ease of use by humans rather than ease of compilation to IBM 701 machine code

edit: https://www.computergenome.com/blast-from-the-past/basic

I know very well that pascal derives from Fortran, in fact it was just a joke

 

[ilan]

i don't know about others but normally I do something for myself and then decide to post it in the forum so I use enough comments I would use for myself. it is hard to go over the whole code and start adding many comments for stuff that should be self-explained from the code itself and if something is not I would also say it is better to ask your question in the thread and I am sure you will get an answer.

give an example where you had a hard time understanding the code and there was a comment necessary in your opinion.

 

[Steve-h]

I really don't want to appear ungrateful for the examples but coming from years of memory constrained assembler and C the whole event driven code thing is bit challenging, a fair few things are similar to C but just different enough in syntax to cause confusion for the slow and not very clever person I am.

Starting out with a blank B4XPages project I tried to understand what the subs were doing. It took some forum help to realize they were mostly being called by the core code, the workings of B4X. That may be explained somewhere but not in anything I have read. A simple comment indicating which subs are called by the the core code and not the code you have written would help the newcomer. In fact unless it is really obvious a simple comment saying what any sub does is really helpful.

Recently I have been puzzling over BLE2 and using the BLEExample. It took some forum help to realize the variable (manager) had been defined to call BleManager

Private manager As BleManager

Then to use a event it had to be written for example

Sub [B]Manager_RssiAvailable[/B](Succsess As Boolean,Rssi As Double)

In the same example

rp.CheckAndRequest(rp.PERMISSION_ACCESS_FINE_LOCATION)

Was a mystery until I figured rp was defined as.

Private rp As RuntimePermissions

And exactly what is happening here is still beyond me.

Sub [B]CreateServiceItem[/B] (service As String) As Panel
 Dim pnl As B4XView = xui.CreatePanel("")
 pnl.Color = 0xFF808080
pnl.SetLayoutAnimated(0, 0, 0, clv.AsView.Width, 30dip)
Dim lbl As B4XView = XUIViewsUtils.CreateLabel
lbl.Text = service
 lbl.SetTextAlignment("CENTER", "CENTER")
 lbl.Font = xui.CreateDefaultBoldFont(14)
 pnl.AddView(lbl, 0, 0, clv.AsView.Width, 30dip)
 Return pnl
End Sub

Sub [B]CreateCharacteristicItem[/B](Id As String, Data() As Byte) As Panel
Dim result As String
 Dim pnl As B4XView = xui.CreatePanel("")
 pnl.SetLayoutAnimated(0, 0, 0, clv.AsView.Width, 40dip)
 pnl.Color = Colors.White
 Dim lbl As B4XView = XUIViewsUtils.CreateLabel
  lbl.Text = Id
 pnl.AddView(lbl, 0, 0, clv.AsView.Width, 20dip)
 Dim lbl2 As B4XView = XUIViewsUtils.CreateLabel
Try
  lbl2.Text = BytesToString(Data, 0, Data.Length, "UTF8")
result = BytesToString(Data, 0, Data.Length, "UTF8")
 Log (result)
 Catch
Log(LastException)

 lbl2.Text = "Error reading data as string"
  End Try
  lbl2.TextColor = 0xFF909090
 lbl2.TextSize = 14
 pnl.AddView(lbl2, 0, 20dip, clv.AsView.Width, 20dip)
 Return pnl
End Sub

Just simple comments saying what a variable is used for or what a sub is doing helps enormously. In assembler I got into the habit of commenting almost every line of code. I completely get the point that if you understand something it is difficult to figure how any of it is anything other than obvious.

B4X is a fabulous tool and the forum support superb, I am conscious however of not asking too many questions where the answer is really obvious as that will become annoying to those who are kind enough to reply.

 

[AnandGupta]

@Steve-h I understand your feeling.

As I can make out, it will be better if you try another language for a given environment.

Ok, let us say you want to target Desktop, then instead of B4J, try VB.Net first and make few simple windows program. Then try same in B4J. Now you will see how B4J make life simpler by hiding some of the complexity for same program.

Now, if you want to target Android, try Android Studio first. Keep in mind Android is quite different beast than Desktop. What is obvious in Desktop is wrong in Android. You will have to think 'tangentially' here. Then try B4A for same app. You will instantly find the difference.

B4X make development easier by hiding complexity, but in return it expects you to know the environment basic. It took me few years of lurking the Forum to understand Android and I am a full time Windows only developer. Now I make Android app with same ease as I make Desktop app.

These are my personal suggestion which I feel will give you grip of the B4X language.

As for the codes going above your head, start putting Log("1") , Log("2") ,.. before / after each line which is creating confusion. If a variable is making no sense, you can put Log(<var>) and it output in log window. No fuss in converting a int to string etc. This will help you get the flow of the things.

Read klaus booklet, (best for beginners)

[B4X] Documentation Booklets

The B4X documentation booklets are available in PDF format, Download Link. All files are included in the zip file in the link above, pdf booklets and all the source code. You can also download all the source code for al booklets, SourceCode. These booklets cover the four B4X platforms. Some...

www.b4x.com

It explains all nitwits all smaller bits of B4X language with example codes.

 

[AnandGupta]

Nitwits? Or nuisances? Or maybe nuances?

Oh I used the wrong word.
I meant 'all smaller bits', will correct it.

 

[emexes]

Oh I used the wrong word.
I meant 'all smaller bits', will correct it.

"smaller bits"? Perhaps this was the word your subconscious had in mind:

which is obviously a mildly risky (or risque?!) word to use in some arenas but here you are amongst friends

 

[LucaMs]

Granted that I haven't read all the posts on this thread...

Here is a good reason (there are other more important ones) to avoid setting a variable of a class as public, so as not to have to struggle to create a property routine: you cannot add a comment to a variable, instead you can to a property.

Someone has this bad habit and, to save time, create this type of variable; I don't mention names I hope he reads and agrees.

 

[ilan]

Granted that I haven't read all the posts on this thread...

Here is a good reason (there are other more important ones) to avoid setting a variable of a class as public, so as not to have to struggle to create a property routine: you cannot add a comment to a variable, instead you can to a property.

Someone has this bad habit and, to save time, create this type of variable; I don't mention names I hope he reads and agrees.

I have not understood a single word.
maybe put an example so i can also understand what u mean.

 

[LucaMs]

I have not understood a single word.
maybe put an example so i can also understand what u mean.

It's your fault and the site's fault: it's time you all learned Italian

"Someone" has a bad habit of creating a public variable in a class, rather than creating a property of that class; the reason is that it is done much faster.

Simple example:
I have a class Person and instead of creating the Age property, I create a public variable Age.

It goes without saying that you will not be able to add a comment to that variable (and, more importantly, you will not be able to carry out checks on the value assigned to it); in this case its meaning is obvious, but it is not always the case.

 

[rabbitBUSH]

Recently I have been puzzling over BLE2

Oi gee @Steve-h - - you really picked a difficult starter example. I have a number of postings on BLE having gone down that road too - not as a first or early project - the thing about BLE is its a conceptual leap anyway. BLE is just a complex function seemingly devised by a clever mind somewhere.

The mix of comments here really represents a difficulty between the learning curve which has to be attended by copious reading and the improbability of imparting that knowledge already acquired by the practiced developer.

I have small experience in student days with assembler and am sure that no matter now many comments you place in the code - most of the time I would be just as lost as to what is going on - without having to still look it up - somewhere.

I had the same feeling when starting out here a couple of years ago - and the BLE project (based on same example) lead me to so much reading pointed to by forum members - most of which was just as confusing - - -

Comments are always welcome - but then most comments mean something to the developer - and can be mysterious to people like you and I - at first - you get to know the different responders after a while - and commensurately to understand their meaning.

Have a look for my BLE posts if you've not seen any - I hope I make a good job of asking questions - that elicit excellent responses.

Incidentally - I banged my head on an aspect of my BLE project for a couple of weeks - to realise in the end - I had not included the setnotify part.

That all said - often I get responses and really - one has to read the new code really carefully to see the difference - its often short and inserted as changes to the original - as we all know reading code is the best way to learn.

And - me being the world's worse code-commenter - your point is well made. But members do expect that one has to walk one's own learning curve through the guidance. This is the only forum I have ever found where the ethos is being helpful.

 

[Raart]

Ok, I feel maybe I know what is the culprit here.
I remember the times (the 70ees) where where we were used to cut a hair in four (longitudinally) to obtain routines consuming a single clock cycle less then others.
That was real directly discuting with the hardware.
Now we are playing with things like object oriented programming, abstraction and the like, a very different programming environment.
For assembly programmers this high level programming platforms are as being on Mars, a completely different world.
What I feel right to suggest are two things:

a. for assembly programmers, get a couple of books about object oriented and event driven programming (there are plenty of) and learn that basics.

b. for experienced OOP languages programmers, document what you do as it serves both to you as to others in understanding what you have done. It doesn't mean to go on commenting every single line of code (this is a bad practice in assembly code either), but at least what an object does, with its characteristics, and the main process actions. The old good flowchart is a quick way to make things clear with no effort.
Comments make sense where spaghetti programming is still your way to do things.
Don't expect others and you in the future will be happy with your today messy code.

My 10 cents.