Does size matter?

ElectricAye

I noticed that a lot of Spin programs have variable names like ptr or vkk or zt. Personally, I like to give my variables names that will instantly make sense to me 6 months after I've written the program, names like SharedMemoryAddress, or TimePartitionWidth. What I'd like to know is: does size matter to the actual execution of instructions? If I fill my program with such elegantly descriptive names, will I pay a penalty in slowing down the processor? .... or do things like names just get digested into some sort of electronic grunt, same as ptr or kwt or wtf?


thx,
mrk

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
It might be the Information Age but the Eon of Ignorance has yet to end.

Beau Schwabe

ElectricAye,

In this case, size does not matter.· There is a limitation of 30 characters as to·how big it can be.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Beau Schwabe

IC Layout Engineer
Parallax, Inc.

ElectricAye

So, in other words, it wouldn't kill anyone to write code that had variable names the whole world could understand almost at a glance? I mean, 30 characters, wow! You could almost turn your code into Gravity's Rainbow with that kinda expressive elbow room.

I suggest that, from now on, variable names used in the Object Exchange must be at least 15 characters long. How's that for a step toward helping newbies?

That, and a few comments here and there to let us know what's doing what.

Anyway, don't worry guys. Put away your anxieties. You've heard the expert: size doesn't matter!

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
It might be the Information Age but the Eon of Ignorance has yet to end.

BradC

It does when you have to type it 35 times!

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Pull my finger!

Ale

I always use names like: i, j, k, a and so on. later I realize how unreadable the code is and using replace command... i give the variables nicer names... after I wrote 34 times 'x' instead of 'coordinateXinMilimeters'.

(But for the size matter, do not ask a woman! you may not like the answer )

hippy

Good coding practice should always be followed, comments, descriptive variable and constant names always help but it is common to use 'i' for index and 'ptr' for pointer etc so there are no hard and fast rules.

At the heart of this is what the Obex is, what role it fulfils and who the audience is. Different users of it have different expectations. Programmers generally produce amazing and useful programs but do not excel when when it comes to descriptiveness and documentation. I wouldn't like to see people excluded simply because they are time limited or lack other resources and skills. Something's always better than nothing and contributors are being incredibly generous in publishing to Obex in the first place.

Perhaps Obex needs some mechanism to indicate how useful or usable code is but I'm not sure how that would work; what a programmer with experience sees as easy to use and follow may not be how a newcomer sees it.

jazzed

I formed the habit of using 'ii' instead of 'i' around 1987. It occured to me that if I need to do a search and replace for some reason like 'ii' to 'tokenIndex', it would be much easier. Of course if one can use 'i' as a 'local text' variable that is only on 3 or 4 lines, it doesn't matter much, but the first real language I knew that was actually useful ... 'C' required variable declarations.

Now, lets count the number of 'i' and 'ii' in the last paragraph ... 22 or 23 'i' and 2 'ii' ....

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--Steve

waltc

Descriptive identifiers would be nice but don't expect it given the wildly varying skillset of the people who do the coding. And unless the coders are working to NASA or DoD standards you can forget about getting useful identifiers.

What would be nice if every object in Obex included PDL - basically pseudo code that describes in some detail whats going on, what variables do what, etc. It would give enough information that another programmer could build a object/program from it.

FWIW

Ken Peterson

It all comes down to this...do you want code, or do you want readable code? Hippy made a good point. Many of us who write code for the Propeller don't have the time or the inclination to do a lot of documentation. Unless we wrote the code for work, and then it's a lot less likely we'd publish it here. If we were required to generate documentation or follow standards then we might not publish at all. Sometimes you just have to scratch your head and say "What the heck was he thinking??". I do that with my own code sometimes...especially if I haven't touched it for years.

Now I'm not saying that good documentation is a waste of time, but I guess you have to appreciate what you can get for free.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
·"I have always wished that my computer would be as easy to use as my telephone.· My wish has come true.· I no longer know how to use my telephone."

- Bjarne Stroustrup

ElectricAye

Ken Peterson said...
Now I'm not saying that good documentation is a waste of time, but I guess you have to appreciate what you can get for free.

Oh, i LOVE what I can get for free. I appreciate every bit of it. Now how much do I have to pay for a semi-self-explanatory variable name or a well placed comment? How much extra would Parallax have to charge per chip if they hired some people to document the objects fundamental to its application? How many chips do they sell per year? How many more chips would they sell if the Prop were virtually a plug and chug item?

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
It might be the Information Age but the Eon of Ignorance has yet to end.

Sniper King

ElectricEye, I love you man...

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
·- Ouch, thats not suppose to be hot!··


Michael King
Application Engineer
R&D
Digital Technology Group

Ron Sutcliffe

Have you actually read the extensive documentation in the form of the Prop Manual.

Then of course there is the Tutorials, Tricks and Traps etc, etc. Once you have got through those you will have little trouble following much of the code in the OBEX.

Spin is not difficult, most seem to make sense of it within a couple of days. Spin·is like most things, you get out what you are prepared to put in.

If all else fails there are a·many in this room that will bend over backwards to help.

Regards

Ron

ElectricAye

To answer Mr. Sutcliffe,

Yes sir, I have read almost everything I can get my hands on and I have made very good progress. And one of my favorite passages in the Spin scripture is the following, found on page 9 of the PE Kit, Objects lab:

said...
Each public method’s documentation should have
enough information for a programmer to use it without switching back to Full Source view to reverse
engineer the method and try to figure out what it does. This is another good reason to pick your
method and parameter names carefully, because they will help make your documentation comments
more concise. Below each public method declaration, explain what the method does with
documentation comments. Then, explain each parameter, starting with its name and include any
necessary information about the values the parameter has to receive. Do the same thing for the return
parameter as well.

Please understand, I am not casting aspersions upon the community of volunteers who are so totally cool enough to share what they have created with the Object Exchange (AKA Obex for those of you who don't know what an Obex is.) That's not my point. I don't expect fully documented code from people who are having fun with this. Documentation is tedious and boring. My position is that Parallax could really help us newbies and probably help themselves if there was a core group of well documented Objects that were fundamental to Prop's usage. These would not only be blessed through testing but could also serve as training tools.

I seem to hit some kind of nerve with people on the forum when I suggest comments be included with code. I'm not a psychoanalyst, but I'm guessing this sort of anxiety stems from a sense of proud ownership the community has toward the Objects they are posting for free. In some sense perhaps contributors to the Object Exchange don't want Big Daddy Parallax getting involved with some of the objects that have already been created. Perhaps Parallax can provide some kind of remedy for those insecurities and provide amble credit and/or compensation to the donators of those objects while at the same time creating an official packet of professionally commented code.

Mind you, I doubt my little campaign of asking for comments is ever going to help me. By the time Parallax ever gets around to documenting things, I will be so used to working with Prop that it will hardly matter to me. I'm just speaking as a newbie entering this situation and giving my humble opinion. Lawrd knows there is already a lot of material Parallax has provided. I could not have gotten up to speed so quickly without it - but a glaring gap in this otherwise stellar stairway to getting intimate with the Propeller is the sudden lack of comments one is faced with when encountering the objects available for fundamental operations and interfaces. All I'm saying is that a little bit of effort along the lines of code commentary could go a long way.

happy commenting,
Mark

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
It might be the Information Age but the Eon of Ignorance has yet to end.

jazzed

The "prop-bible" section you quote is taken for granted for sure. It is describing an API (Applications Programming Interface).

The term API is often loosely used to mean just function/method name, parameters, and return code interface. Industry professional C programmers use APIs all the time, but not everyone here is a professional. Also, the more coding experience one has the less likely they are to produce such API documentation unless they have·worked long term or are working in a specific environment·requiring it.

I'm a fan of javadoc and doxygen markup for APIs. Such markup allows for web pages and several doc standards including .rtf to be generated automatically (a workable markup can be added to spin with a little effort). Again, it is a matter of Professional or other discipline, but such tools allows for some good automatic from code to written word communication.

Here is an example of doxygen (similar to javadoc) markup for spin:

Code:
 
PUB isBreakPoint(bppc) | ii
{{
/**
 * find out if PC is on a breakpoint
 * @param pc the program counter value to check for breakpoint
 * @returns non-zero or break number if pc is a breakpoint
 */
__ bool isBreakPoint(pc);
}}
 
Documentation output:
_______________________
PUB  isBreakPoint(bppc)
/**
 * find out if PC is on a breakpoint
 * @param pc the program counter value to check for breakpoint
 * @returns non-zero or break number if pc is a breakpoint
 */
__ bool isBreakPoint(pc);

The function signature "bool isBreakPoint(pc);" is there for doxygen to pick up for API since it only understands C notation. The line over PUB in the resulting html or rtf documentation is quite annoying, but not unreasonable.

The only way to get high quality documentation is to require peer reviews before posting code to OBEX. This is of course not workable and would discourage some high quality programmers from sharing innovative solutions since peer reviews can get more contentious than the worst forum flaming replies.


▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--Steve

hippy

ElectricAye said...
By the time Parallax ever gets around to documenting things, I will be so used to working with Prop that it will hardly matter to me.

I think that is one of the reasons it probably hasn't happened. Once newcomers have got over the hurdles it's largely irrelevant. True, it might help newcomers get over the hurdles sooner. Currently the Propeller isn't positioned for the inexperienced but that could well change in the future.

Tracy Allen

I'm in favor of
-- short variable names in re-usable code, where the intent of variables may change dramatically
-- short variable names in math and state machine code, where long names tobscure the overall logical structure (forest for trees).
-- short but not too short, keep the names searchable.
-- long names for top level application variables.
-- ample comments, and deeper when tricks are used.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Tracy Allen
www.emesystems.com

Sniper King

At the risk of sounding stupid, maybe a little work on a usable, reasonable "standard" is in order.· I am not suggesting at all (I mean it) that we need rules or anything but a discussion on a reasonable standard that can be documented on this or maybe a new thread.· As a collective mind we could come up with a strong header documentation format that could go a long way to make everything this forum beleives in more efficient.· honestly, evrybody should be happy all the time! Instead of arguing our positions, lets do something.·

This could cause the planets to align and peace to break out on earth... or something!

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
·- Ouch, thats not suppose to be hot!··


Michael King
Application Engineer
R&D
Digital Technology Group

lonesock

I do think auto-completion would be a great feature in the Propeller Tool.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
lonesock
Piranha are people too.