 |
|
 |
| Parallax Forums > Public Forums > Propeller Chip > Newbie thoughts.... Are my code commenting expectations for demo programs to high? | Forum Quick Jump
|
 | 
Nick Mueller
Registered Member
      
Date Joined Apr 2007
Total Posts : 697
| Posted 8/20/2009 1:29 AM (GMT -8) |   | > I kinda like MINIMAL commenting. (at least for SPIN)
> 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:
MOV AX, 0x0A; ' Write 10 to AX
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 | | Back to Top | | |
|
StefanL38
Registered Member
Date Joined Sep 2006
Total Posts : 958
| Posted 8/20/2009 5:58 AM (GMT -8) | | @nick and all other object-uploaders
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 | | Back to Top | | |
|
Cluso99
We live onboard
Date Joined Apr 2008
Total Posts : 2277
| Posted 8/20/2009 6:37 AM (GMT -8) | | Stefan, with respect, what you are asking will not be done. These objects are placed there by the generosity of their donors who have done somethng that they feel others may be able to use too. They are placed there free, no money, no donations. They are not necessarily going to take the considerable amount of time to do what you ask. Most likely they are onto a new exciting project.
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: | | Back to Top | | |
|
ElectricAye
Registered Member
Date Joined Jul 2008
Total Posts : 972
|  Posted 8/20/2009 6:55 AM (GMT -8) | | WBA,
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. | | Back to Top | | |
|
heater
Registered Member
Date Joined Feb 2008
Total Posts : 1834
| Posted 8/20/2009 7:05 AM (GMT -8) | | WBA. The debate about comments in code has been going on for decades.
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. | | Back to Top | | |
|
NetHog
Registered Member
Date Joined Nov 2007
Total Posts : 99
| Posted 8/20/2009 7:33 AM (GMT -8) | | |
I've been the technical lead for major projects and mentoring engineers for years.
My general advise on code comments is this:
At the level of a method/function/procedure:
What this method/function/procedure does, how and why you would use it, with examples.
At the level of a block of code within a method/function/procedure:
Why the block of code is doing whatever it is doing.
As noted above, the following is a bad comment:
// subtract 32 from F, multiply by 5, divide by 9
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:
// temperature is required in Celsius. It is currently in Fahrenheit
// it needs to be converted.
C = (F - 32) * 5 / 9;
Which explains why you're performing the calculation you're doing.
| | Back to Top | | |
|
Phil Pilgrim (PhiPi)
Registered Member
Date Joined Feb 2006
Total Posts : 6000
| Posted 8/20/2009 7:46 AM (GMT -8) | | This is a problem that has been solved very neatly in the Perl community using the POD (plain old documentation) model. POD is a commenting system that uses markup tags to identify simple formatting cues, so that professional-looking documentation can be produced from the source code itself. Submissions to CPAN (Comprehensive Perl Archive Network — like our OBEX, only more extensive) are required to have POD sections, so that the documentation can be rendered online to HTML. That way, potential Perl module users can reveiw the docs before installing the modules themselves.
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 | | Back to Top | | |
|
SRLM
Registered Member
Date Joined Jul 2008
Total Posts : 2720
| Posted 8/20/2009 7:46 AM (GMT -8) | | | Good minimal documentation (that I like) is to preface each function (aka method) with the purpose of the function, the meaning of the parameter list (with each parameter meaning defined), and the meaning of the return value or output. This gives the beginner enough to work with (how to use the function) while not taking too much time. Of course, the code should probably have comments as suitable. | | Back to Top | | |
|
Nick Mueller
Registered Member
Date Joined Apr 2007
Total Posts : 697
| Posted 8/20/2009 8:19 AM (GMT -8) | | @NetHog:
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.  ... Kidding.
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 | | Back to Top | | |
|
David B
Registered Member
Date Joined Jul 2004
Total Posts : 320
| Posted 8/20/2009 8:56 AM (GMT -8) | | A problem with the object exchange is it's a collection of everything - great code, duplicated code, buggy code, newbie code, expert code, library code, tutorials, code snippet examples.
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. | | Back to Top | | |
|
Erik Friesen
Registered Member
Date Joined Jun 2007
Total Posts : 537
| Posted 8/20/2009 9:28 AM (GMT -8) | | | As a reference, one may check out the microchip pic24 starter kit code, which is written in C. It seems to be quite well commented, however it is very difficult to follow anything at first glance. Although code can be commented perfectly, until one understands what everything does and how it works together, it really doesn't do much good. I guess what I am saying is too many comments doesn't allow you to see the forest for the trees. | | Back to Top | | |
|
WBA Consulting
aestheticacoustics.com
Date Joined Nov 2007
Total Posts : 341
| Posted 8/20/2009 11:53 AM (GMT -8) | | | | |
|
waltc
Registered Member
Date Joined Jul 2008
Total Posts : 145
| Posted 8/20/2009 12:29 PM (GMT -8) | | Well written Code ought to be self-explanatory but often isn't. I've seen modern day HLL code examples and documentation by so-called professionals that was garbage and may as well been written by monkeys on crack and I've seen Fortran 4 code that was self-explanatory and clear as day.
That said, if one wants to learn how to comment or document code pick up a copy of Code Complete. | | Back to Top | | |
|
CounterRotatingProps
Ah, just another dull day for the shoemaker...
Date Joined Jul 2008
Total Posts : 1014
| Posted 8/20/2009 12:45 PM (GMT -8) | |
WBA Consulting said...
EXCELLENT FEEDBACK for my question. [...] but I still have a few unanswered questions. Like:
1. What is the "printLong(n)" method for?
2. Why is there a DAT block at the end of the code?
3. Should the printRawValues method be removed since the demo uses inline code to display the raw values? Hi Andrew,
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
| | Back to Top | | |
| 38 posts in this thread.
Viewing Page : 1 2 |
| Forum Information | Currently it is Saturday, November 21, 2009 11:35 AM (GMT -8)
There are a total of 393,858 posts in 55,536 threads.
In the last 3 days there were 84 new threads and 709 reply posts. View Active Threads
| | Who's Online | This forum has 17692 registered members. Please welcome our newest member, old guy.
58 Guest(s), 14 Registered Member(s) are currently online. Details
Siri, keith_kw, Jay Kickliter, Mike Green, Bob Lawrence (VE1RLL), Alsowolfman, Dogg, dMajo, hover1, ErNa, Harley, Tubular, Leon, MicroDirk |
Forum powered by dotNetBB v2.42EC SP2.02
dotNetBB © 2000-2009 |
|
|