Newbie thoughts.... Are my code commenting expectations for demo programs to hi
WBA Consulting
Posts: 2,935
I have been working with the propeller for just a few months (official start was UPEW). As I have been going through the manual, example programs, and tutorials in my learning adventure I spend a lot of time disassembling the code so I can make sense of each line. This has greatly helped my learning curve because understanding how code works while the path of the code is jumping all around has been a little difficult. I basically cut and paste code blocks into a single stream so I can clearly see the flow.
Anyways, so far I have been less than proficient at getting useful information from the commenting in code examples. As a newbie, I can immediately tell when I will be able to make sense of an object or code example by how clean the comments are. I thought maybe I was expecting too much, but some of the examples have comments that are exactly what I expect.
The Sensirion object is an example of an intense and useful object that lacks helpful comments. I have torn it apart and pieced it together line by line to make sense of what each step is doing. I use the manual to look up each command and determine what the line of code is "really" doing. Here's an example:
Has nothing for a comment. However, here's my note for this line of code:
rawTemp equals the value returned by the readTemperature routine in the SHT (sensirion.spin) object after being formatted by the FFloat routine in the f (Float32.spin) object
That detail makes it easy for me to review the code and know what that line is doing as I come to it. I know that not all objects are designed for use by a beginner, but detailed comments seem to be a resolution to many headaches in this newbie's opinion.
Thanks to all those who do comment their code cleanly......
ps, the tutorials in the Propeller Tool Help section are awesome!
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
Post Edited (WBA Consulting) : 8/20/2009 10:10:35 PM GMT
Anyways, so far I have been less than proficient at getting useful information from the commenting in code examples. As a newbie, I can immediately tell when I will be able to make sense of an object or code example by how clean the comments are. I thought maybe I was expecting too much, but some of the examples have comments that are exactly what I expect.
The Sensirion object is an example of an intense and useful object that lacks helpful comments. I have torn it apart and pieced it together line by line to make sense of what each step is doing. I use the manual to look up each command and determine what the line of code is "really" doing. Here's an example:
rawTemp := f.FFloat(sht.readTemperature)
Has nothing for a comment. However, here's my note for this line of code:
rawTemp equals the value returned by the readTemperature routine in the SHT (sensirion.spin) object after being formatted by the FFloat routine in the f (Float32.spin) object
That detail makes it easy for me to review the code and know what that line is doing as I come to it. I know that not all objects are designed for use by a beginner, but detailed comments seem to be a resolution to many headaches in this newbie's opinion.
Thanks to all those who do comment their code cleanly......
ps, the tutorials in the Propeller Tool Help section are awesome!
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
Post Edited (WBA Consulting) : 8/20/2009 10:10:35 PM GMT
Comments
OMG! You should program in COBOL.
Nick
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!
The DIY Digital-Readout for mills, lathes etc.:
YADRO
Sometimes (as you found out) the best example is JUST the code with minimal comments.
It worked for you, look how it forced you to learn the code,
to the point that eventually you will be able to read it like english.
I kinda like MINIMAL commenting. (at least for SPIN)
It forces us to learn.
Assembly is just a mess and needs major commenting.
> It forces us to learn.
One always has to learn. Learn the language at first, and then you'll understand.
I've seen lines like these:
OMG! What an idiot! First, he already has stated that AX is written some value to. Second, if he thinks decimal (10) he should write it in decimal (MOV AX, 10).
In languages that are easy to read (higher level languages like SPIN, C, BASIC, ...) per-line-comments are mostly useless. Not always!
Comments that describe the flow are much more helpful.
Frequently when I code something complex, I start with the comments. This makes the skeleton for the logic. Then I fill in the code.
Nick
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!
The DIY Digital-Readout for mills, lathes etc.:
YADRO
If you want what I would call a good example example (my definition - as there is a lot of my comments and code in here - I have been programming >30 years and a programming instructor in the late 70's and early 80's) take a look at the ZiCog009_demo_rr097.spin code and the TriBlade driver code posted on the second last page of the TriBlade thread (link in my signature) - it's called zicog009_demo_rr097....zip
Postedit: What you are looking for are tutorials such as in the Prop Manual, the wiki has some, OBEX has a vgaLearn object. OBC has a Cookbook that may be useful too.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Links to other interesting threads:
· Home of the MultiBladeProps: TriBladeProp, RamBlade, TwinBlade,·SixBlade, website
· Single Board Computer:·3 Propeller ICs·and a·TriBladeProp board (ZiCog Z80 Emulator)
· Prop Tools under Development or Completed (Index)
· Emulators: Micros eg Altair, and Terminals eg VT100 (Index) ZiCog (Z80) , MoCog (6809)
· Search the Propeller forums·(uses advanced Google search)
My cruising website is: ·www.bluemagic.biz·· MultiBladeProp is: www.bluemagic.biz/cluso.htm
Post Edited (Cluso99) : 8/20/2009 9:51:49 AM GMT
uploading an object means you say yes that others can use your object too. You WANT to share it with others
Now my opinion is: to be kind to newbees means you write a short manual about using the object.
ONE democode with some small comments is not enough.
To newbees it will happen they can download the demoprogram start it say wow that's a great demo
and then scratching their head hm no how to I modify the democode to my needs ?
and keep on scratching because there is no manual.
imagine the use of a car. If you want to use it it is enough to know how to drive it.
Of course as more as you know about the car is working the more you can help yourself or modify the car.
the common comments in the objects is details: this variable for that and this for that etc. etc.
but there is now detailed info about how to use it in different situations
Now to get back to the car-picture: if the manual of the car would tell you this screw together with this 3 ones holds
the backseat, this screw holds that. This tube contains brake-fluid etc. etc.
But NO information about how to use it as the whole thing driving the car.
or no information like this: it is a very modern car that has no classical "key-ignition" but a RFID-reader and a startbutton underneath the backseat
you will not be able to use the car!
Of course it would be very silly to hide the ignition button under the backseat
cars are still so similar to each other that after looking around for one minute in the cockpit of a BMW118 you will find the slot where to put the RFID-key into and the iginitionbutton
but with propeller-objects the variaty of their parameters and methods - they are so different like you would create a car with an "ignition-system" like this
put in five RFIDs into the slots 2 of them after each other in the same slot under the driverseat one in the middle of the cockpit and the other two rfid-chips are hided
in small leather-balls which have to lay next to the tacho ! Of course it would be compeletly mad to create something like this. This is just a picture to show possible the variaty of objects.
How would you ever be able without a manual to use this ignition-system ??? NEVER !
For something like that you need a manual on HOW to use the WHOLE thing.
Saying you have to learn all these details is like saying
dismount the complete car to find out how this crazy ignition-system works.
If you include 3 to 5 different example-demo-codes on how to use an object it will become much clearer what the BASIC PATTERN of its use is.
best regards
Stefan
If you place that restriction, noone (or very few) will post anything and then where would you be? I document my code for any programmer to read, but unfortunately, not for the novice. This is an understable problem for beginners. They need to find the tutorials and go through them, but that is unfortunately a fact of life. Novices need to read books (sometimes buy if necessary).
The biggest problem I see is not the lack of tutorials, but where to find them. There are a number of good ones around on various topics·but no complete index, despite the fact this is asked all the time. A lot of information can be·learned by reading the forum threads, particularly the newbie and beginner threads.
So my friend, novices have to ask here on the forum where lots of people are so willing to help.
Please do not take this the wrong way. It is meant in the nicest way. Enjoy and ask.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Links to other interesting threads:
· Home of the MultiBladeProps: TriBladeProp, RamBlade, TwinBlade,·SixBlade, website
· Single Board Computer:·3 Propeller ICs·and a·TriBladeProp board (ZiCog Z80 Emulator)
· Prop Tools under Development or Completed (Index)
· Emulators: Micros eg Altair, and Terminals eg VT100 (Index) ZiCog (Z80) , MoCog (6809)
· Search the Propeller forums·(uses advanced Google search)
My cruising website is: ·www.bluemagic.biz·· MultiBladeProp is: www.bluemagic.biz/cluso.htm
I have moaned and sobbed about the lack of comments in the OBEX code since day 1 of my joining the forum but it seems to do no good. When I complain about the lack of comments, I seem to run up against some kind of cultural or neurological barrier here. Perhaps it is a right-brain/left-brain issue. I'm sure many computer-oriented personalities have experienced a similar type of barrier when trying to explain to an English major what a bandwidth is. My biggest disappointment is that people still cling to their infantile need to lay out their code using "electronic grunt": two or three-letter variable names that are often worse than useless for learning or debugging.
Save yourself. Comment your code.
The problem is: Who is the target reader?
Different reader will be comfortable with different levels and style of commenting.
When writing a language tutorial for newbies to that language or instructions for the use of a new Prop object then detailed line by line comments can be helpful and appropriate and you readers will thank you for it.
But if your readers are proficient in the language and libraries (or objects) in use in your code then that level of detail in comments on a line by line bases will soon drive them nuts. They will be annoyed to have to read all that redundant text on the off chance that there is some detail documented in there that is important.
Trust me. If you spend enough time reading and writing Spin and/or PASM and using various objects (or any language for that matter) you will find yourself tiring of that repetitive detail.
Now there is another important point about comments. Comments in code are ALWAYS wrong. What happens is that code is not a static thing. It gets bugs fixed, it gets features added, it gets optimized etc etc. Perhaps by different people. Soon you find that the comments are neglected and not updated in line with the code.
Now you are in a world where the comments are actually working against you. You don't know what to trust. The code or the comment.
In a professional environment the judgement about comment style is usually easier to make. You know your audience is fellow coders who are up to speed on the language, the libraries, classes, methods, objects etc etc.
Or if they are not they should be getting some training.
In the Propeller Object Exchange it's not so clear. The code is written by gurus who speak Spin in their sleep. But then it is freely available for anyone of any skill level to look at. So surely here you are asking for more commenting.
It's a difficult balance.
There are some general guidelines to commenting:
Try to make the code self commenting, that is use meaning full object, method, variable names.
Describe what the object is and what the methods do so that users can use it with out reading the code.
Describe the inputs and outputs of methods, expected ranges, error conditions etc.
Do point out odd bits of code. For example if there is a line of code tweaking an undocumented bit in some hardware interface one should probably comment the reason for it being there.
I'm sure others could contribute more to this list.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
For me, the past is not over yet.
My general advise on code comments is this:
At the level of a method/function/procedure:
At the level of a block of code within a method/function/procedure:
As noted above, the following is a bad comment:
C = (F·- 32) * 5 / 9;
It tells you nothing you don't already know, unless you don't understand the "=", "-", "*" "/" operators.
The following is a good comment:
// it needs to be converted.
C = (F·- 32) * 5 / 9;
Which explains why you're performing the calculation you're doing.
Good documentation often takes longer to write than the code itself. The only possible way for OBEX submissions to be "properly" documented is for that documentation to be required and enforced by those who review and approve the uploads. Otherwise, human nature being what it is, it'll never get done. But I suspect that if such a requirement were put into place, OBEX submissions would drop to near zero.
-Phil
Good extension of my negative example! That's how thing hav to look like!
> Now my opinion is: to be kind to newbees means you write a short manual about using the object.
> ONE democode with some small comments is not enough.
Wait! There are several levels of comments/documentation.
A user of a module should never ever have to look at the source. That's a black box. As soon as you have to open it to understand how it works, the magic code escapes.
From an outside-view, comments look quite different. Overview what that thing does, explanation of how things fit together, influence them, exclude them (either this way, or an other). Usage and explanation of constants so the user can change the behaviour without poking around in the code, etc.
And then a demo-program that simply runs, has enough comments to show you where to change parameters etc. But the demo-program is mostly missing.
Nick
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!
The DIY Digital-Readout for mills, lathes etc.:
YADRO
Maybe Parallax could consider an expanded form of object exchange.
These categories aren't fully thought out, but may be a starting point for discussion:
1. newbie code examples
simple, well commented
not the place for clever tricks
2. library objects
finished products, ready to be installed used as finished library code
interface must be commented, but code itself is not necessarily deeply commented
periodically (maybe yearly) start a new folder.
Let users add favorite objects from earlier years; let the rest remain in the earlier folders.
So at any time, the current year's folder contains the best set of older libraries plus new submissions.
This way, buggy and development code gets regularly aged out.
3. files of code snippets to be copied and pasted into user code
helpful code segments not extensive enough to be dedicated to a full object
designed to be copied and edited to fit a users needs
string handling utilities
math utilities
array handling
examples of complex argument passing: pointers to memory, spin to asm, etc.
4. documentation
Here again, maybe yearly versioning of folders may regularly weed out older and unuseable documentation.
By using yearly versioning folders, Parallax could let the user community do the weeding out of old and unuused code without the struggle of having to examine each object submission for usefulness.
All Parallax would need to do is provide the folder areas, and let users submit the code.
I agree. As I said, it's a neurological thing, a hard-wiring of particular brains. I would never suggest that comments be required. Let freedom ring.
I think this is a great idea. But I think when it comes to Objects, they are utilizing the "Crowd Sourcing" concept. en.wikipedia.org/wiki/Crowd_sourcing
And you get what you pay for.
Isn't there some kind of capability in the Propeller editor that allows you to strip away comments and look at just the pure, pristine, unadulterated code?
Not another ViewPort commercial response please !!
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--Steve
Propalyzer: Propeller PC Logic Analyzer
http://forums.parallax.com/showthread.php?p=788230
My understanding is that the Sensirion Demo object is meant to show the usage of the Sensirion.spin object. As a demo program, it should contain necessary comments to make potential users fully aware of how to properly use the sensirion.spin object. In the Sensirion.spin object, I do not expect detailed comments as much, since most of it is somewhat straightforward spin command usage. The simple comments in sensirion.spin make it useful enough for a newbie to understand as long as you review the spin command usage while reviewing the code.
The SensirionDemo.spin program is lacking detailed comments that explain why and how it is doing what it is doing. I have been able to figure a lot out by digging through the code and other spin files its using (IE: float32) and that has been greatly beneficial just as Cluso99 suggests, but I still have a few unanswered questions. Like:
What is the "printLong(n)" method for? (it's not called out anywhere in the rest of the code)
Why is there a DAT block at the end of the code? (it's not called out anywhere in the rest of the code)
Should the printRawValues method be removed since the demo uses inline code to display the raw values?
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
Post Edited (WBA Consulting) : 8/20/2009 10:03:11 PM GMT
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
For me, the past is not over yet.
Very well documented/commented demo program and the zip includes a "manual".
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
That said, if one wants to learn how to comment or document code pick up a copy of Code Complete.
> program, it should contain necessary comments to make potential users fully aware of how to properly use the
> sensirion.spin object.
There's an other point in coding for examples:
You can write easy (for the beginner) code. Means, don't nest function-calls. So the comment at the EOL can get more to the point and thus be reduced.
Many people think, that cramming as many statements into one line makes a faster code. In most cases, that's not true.
Nick
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!
The DIY Digital-Readout for mills, lathes etc.:
YADRO
I always put a mental if statement at the end of each line of code:
IF····· unclear to next programmer with similar level of experience OR unclear to me in 1 year after not looking at this code
THEN· add comment
And you do have to draw the line at some expectation of the next coders level of experience. For instance, if your remaining question could have been answered in comments, then maybe·#1 and #3 need it. But·#2 is answered clearly in the Prop manual and would be redundant to document.
This discussion comes up repeatedly in all language forums.
My rule of thumb is to err on the side of too many comments. If your boss yells at you for not cranking the code out fast enough, don't comment, but then make sure *he* is the one who will have to maintain your code when you leave. hehehehe
- H
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Sometimes also I find I must work the examples several times to get it right. I probably know just enough to be dangerous....
Ken
Some intricate programs actually deserve their own PDF and video, with full explanations
of almost every line and accompanying photos, footage and diagrams....
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
- Some mornings I wake up cranky.....but usually I just let him sleep in -
My tip for learning a language the fastest way is to look at requests for help about non-working code!
Even if you don't understand the problem, you are forced to try to understand the logic, look for pitfalls. And then, if you didn't get it, read the other answers.
If you are into C, you can grind your teeth on obfuscated-C-contest entries.
Nick
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!
The DIY Digital-Readout for mills, lathes etc.:
YADRO
My question for the DAT block wasn't structure based, but rather it's presence. I don't see anything else in the program pulling from the DAT block.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
An example here is Kye's code. xxxxEngine objects. His target audience is obviously farily new programmers even though he uses lots of tricks. The comments for routines (blocks of code) are excellent. The naming is good for this type of audience. IIRC: e.g. module.TransmitCharacter(Character), module.TransmitString(string), etc. However, to the experienced programmer who may call these routines from many places, it is not efficient programming and module.tx(c) and module.txstr(s) would be considered more efficient, yet still readable without comments as the code itself is actually doing the commenting. Upper and lower case is a matter of style and is the subject of many wars.
Now the module itself may or maynot include many comments, other than the required comments at the top of the code regarding usage and history.·History is only required·if it is relevant. My code always has a huge section of changes - that is habit from writing lots of professional code that may introduce bugs (Microsoft·refers to these as undocumented/unintended features)·along the way and I need to know when I did something and why so that if need be I can go back to the original code. And yes, all those changes with _rr020 where '020' is an example of the version number. I have saved them all. Reason as I said is to go back, and second is to prove authorship, should the need arise (never in 35 years). But many times I have had to go back. Once the editor lost a chunk of code that was not being exercised since it was debugged. I recovered the block from source I backed up 3 months earlier (no kidding, and it was a huge amount of work).
So there you have it. If forced to write code with standards for the OBEX I would NEVER post there. To tell the truth, I haven't actually posted there anyway. Most of the code I have done is either (a) not ready for posting there, or (b) too complex to post there, so I answer when the questions arise and point to the thread which contains the code and includes the discussions along the way, and (c) slackness!!!
The only issue that I have been criticised for is that my code is not in the one place in a thread (actually it is in 2 threads ZiCog and TriBlade plus and code is on my website, but not necessarily the latest). My problem is that this is the first forum I have used. I didn't realise you need to reserve the first 2-3 posts so you can post the latest code and documentation at the beginning of the thread and you have to update the original post with new information, meaning the original post discussion starting point is effectively lost. Something I am learning and trying to improve on. But then, some interim versions will be sprinkled throughout the thread, meaning the latest interim versions or parts of it are near the end of the thread.
Now, my signature contains links to some of my threads and also links to "index threads". These indexes (e.g. Prop Tools under·development or complete) contain just a single post each to describe the object and a link to a thread containing the details. Others are encouraged to post their relevant topics there. This is because I felt a lack in this area and a request for these to be "stickies" has fallen on deaf ears.
If you want to understand or use one of my programs or objects and don't understand something, if you post on the relevant thread I will endeavour to answer your questions. But on these threads I don't expect to explain every line of code. I expect a reasonable understanding of code to understand the "guts" of an object. However, to use some of these less technical objects, not much experience should be necessary.
Now, to understand a block of code because it is doing something tricky, I suggest you try and find the original thread discussing this -·it can be difficult, so if you cannot locate it easily (use the link in my thread to search·with google - it will only search this·forum)·then·I suggest you start a thread with a subject "xxxx object: how does xxx routine work?" and in the post include the routine (using the insert formatted code option "#" to maintain indentation). You will usually find many will explain it to newbies even before the original writer sees the post. If you do not get a response in a few days, send a PM to the author with a link to your post asking for help. Don't abuse this though and don't reask the question in the PM. If you are asking maybe others will want to know as well. The author may choose to respond to your thread with "please see original thread xxxx" and a link. There the author should have pasted your question, with the answers. This keeps the questions and answers in the original thread for all to see.
The above is only my opinion and others may disagree. It is meant with the greatest respect to everyone on this great forum.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Links to other interesting threads:
· Home of the MultiBladeProps: TriBladeProp, RamBlade, TwinBlade,·SixBlade, website
· Single Board Computer:·3 Propeller ICs·and a·TriBladeProp board (ZiCog Z80 Emulator)
· Prop Tools under Development or Completed (Index)
· Emulators: Micros eg Altair, and Terminals eg VT100 (Index) ZiCog (Z80) , MoCog (6809)
· Search the Propeller forums·(uses advanced Google search)
My cruising website is: ·www.bluemagic.biz·· MultiBladeProp is: www.bluemagic.biz/cluso.htm
well said !
I just wanted to second your mention of Kye's code examples - here's one he just posted:
http://forums.parallax.com/forums/default.aspx?f=25&m=377829&p=1
Pull it down folks and look at how clean and straight forward his comments are. This is good stuff.
We could probably spiff up the comments in the OBEX - not by the 'stick approach' but by that of the carrot!
Maybe we could have a periodic contest for the "best and clearest commented code" to be voted on by members ?·(secret ballot·of course to not step on toes or hurt feelings)... and perhaps Ken could award some nice Parallax goodie. Although I'm not ready to post my stuff in the OBEX yet, it would be fun to think there's that possibility. And what happens next? Others look to the winner's code for 'how to do it right' .... good things breed good things around here!
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔