Best(?) coding practice in spin?

pacman

I got to thinking, given the controversy that is being stirred-up in the thread "How would you describe Spin as a language?" is there a 'standard' best practice way you folks use in naming your variables?

I do NOT want to start a flame war here.

Many years ago I got into the habit of using Hungarian notation for naming variables, even with some of the PLC's I'm currently coding with I have adopted a syntax to try and help with future maintenance of code (eg tag_G is an integer, tag_P is a Boolean pulse, _F is a real, _T is a timer, etc, etc).

I realise that in spin adopting these sort of names doesn't _force_ types, but I have found this trick has sometimes help me.


So is there a best/better naming convention I should be investigating? Does it matter? What do you do?

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
=================
The future is in our hands.
Which way to the future?
=================

Mike Green

There's no "standard best practice". The names have to be short enough so they're not creating extremely long statements. They have to be meaningful enough to help the reader understand what's going on in the program, particularly after the program hasn't been looked at for a few months. Beyond that it's a matter of personal or corporate taste.

StefanL38

Hello Pacman,

I use this kind of variable-naming c_... for constant or p_... for parameterrs sometimes too.

and I use another two things:

1) SELF-EXPLAING names

2) every part of the code that does ONE senseful thing becomes a PUB (in most cases)

some people call this style of coding "chatty". As I'm the person who has to re-read the code I stay with this style

In my opinion if you want to maintain code years later with this style it is much easier.
And with using hotkeys for marking words or lines and copy & paste done by Ctrl-c, ctrl-v the writing of the letters
is as quick as writing shortnames like sub1, sub2, sub3

best regards

Stefan

MacGeek117

Never underestimate the power of PRI routines!
Self-explaining names almost always work best, especially when looking at code you haven't worked with for a long time.
RoboGeek

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
BS2: $49


SX48 Protoboard: $10

Propeller Protoboard: Priceless

www.apple.com

www.parallax.com

www.goldmine-elec.com

www.expresspcb.com

www.jameco.com

Post Edited (RoboGeek) : 11/7/2009 2:35:51 AM GMT

potatohead

If the product of your efforts, including comments, is something you think you can either reuse, or understand some years later, then you have done well. Bonus points are scored, if others will find it the same.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Propeller Wiki: Share the coolness!
Chat in real time with other Propellerheads on IRC #propeller @ freenode.net
Safety Tip: Life is as good as YOU think it is!

Hugh

I tend to give variables names in camel-case, e.g., "intNumberItems", "boolDataFlag", even if these types are all type byte.

Recently I have started to call PUBs names such as 'callSendData' so that when I see that in the calling PUB it makes more sense (to me at least!)



▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Hugh - the thinking woman's Geoffrey Pyke.

Nick Mueller

Even if SPIN isn't type aware, using some method to show what the variable is meant to be made of is good practice.
I use(d) pXXX fpr pointers, iXXX for ints, bXXX for bools .... eXXX for enums etc. Functions start with a capital. Also the "camel-case" (LOL!) method.
Whatever practice you use, as long as you use it consistently is OK.
There are no "rules" that I'm aware of.


Nick

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!

The DIY Digital-Readout for mills, lathes etc.:
YADRO

pacman

So perhaps _we_ (the community) should come up with some _suggested_ guidelines for inclusion into a sticky thread or the next propeller book.

If we got some form of consistency going then wouldn't that be another step towards making the propeller "even more better"? Imagine being able to pick up the next object and instinctively know when Bob is incrementing an integer or pointer..

Obviously, not everyone would conform (and that would be perfectly OK), but those that did might find it helps the next person who comes wandering in...

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
=================
The future is in our hands.
Which way to the future?
=================

BradC

pacman said...
So perhaps _we_ (the community) should come up with some _suggested_ guidelines for inclusion into a sticky thread or the next propeller book.

If we got some form of consistency going then wouldn't that be another step towards making the propeller "even more better"? Imagine being able to pick up the next object and instinctively know when Bob is incrementing an integer or pointer..

Obviously, not everyone would conform (and that would be perfectly OK), but those that did might find it helps the next person who comes wandering in...

Never gonna happen. Everyone comes from a different background and brings a little of that with them. To try and put a set of guidelines together is like trying to ask everyone to change the way they do what they do. Diversity is good. Unfamiliarity is good. It makes the reader try just that little bit harder to understand what is going on and by having to study the code a little closer they might gain a better understanding of what is really happening.

It's a bit like when I issue a tender. I never, ever accompany it with a bill of quantity. By making the tenderer actually read the drawings to count the quantities, I have a better chance of ensuring they actually understand the project rather than just filling out a spreadsheet.

I know it sounds like work, but as Calvin's dad would say "It builds character". Or in this case, it helps build skill. Like any skill, it gets easier the more you do it.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
If you always do what you always did, you always get what you always got.

jazzed

potatohead said...
If the product of your efforts, including comments, is something you think you can either reuse, or understand some years later, then you have done well. Bonus points are scored, if others will find it the same.

That is the key.

Microsoft once used variable names like szName, but that practice is not promoted much now.
Adding special characters for types is interesting, but that is not really important to everyone.

I prefer camel-case only because under-bars take up space (SPIN identifier size is limited to 32).
Usually the context of an identifier is enough. I capitalize constants out of habit for any language.
I use g<Name> for globals in C for clarity of scope. Spin scope is naturally clear to me.

Added: Well stated BradC.

Nick Mueller

> So perhaps _we_ (the community) should come up with some _suggested_ guidelines for inclusion into a sticky thread or the
> next propeller book.

And adding to Brad:
No, if someone has his style, he won't change it. The good thing is, that any style is obvious (hopefully, more or less) so it should be easily understood after reading some 10 lines of code.

Anyhow, I'm breaking my rules frequently like for the often (ab-)used "i" for a counter in a *narrow* scope (just a few lines). Or "j", if the "i" isn't enough, or "ndx" as an index into an array.


Didn't Don Saks (?) write a book "C/C++ guidelines" or such that has helpful suggestions about that suject?


Nick

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!

The DIY Digital-Readout for mills, lathes etc.:
YADRO

Hugh

For narrow-scope integers I tend to use i, j, k & l as a carry-over from Fortran! I am the one needing re-programming - not the Prop.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Hugh - the thinking woman's Geoffrey Pyke.

agodwin

Nick Mueller said...
Even if SPIN isn't type aware, using some method to show what the variable is meant to be made of is good practice.

Nick

I think perhaps BECAUSE spin isn't type-aware, this might be a good thing.

I've always hated 'hungarian' notoation, feeling that it's the compiler's job to look after types, not mine. I accept that it might be occasionally useful to distinguish object sizes to avoid accidental truncation, but unnecessary for distinguishing pointers etc. .. the C compiler will tell you about that.

But one of the errors I frequently make in spin is failing to sign-extend when assigning or calculating using a word or byte operand. A reminder in the variable name might help.

Perhaps more important is access : I tend to communicate between cogs using shared variables and a reminder that I need to think about atomic operations (either with careful usage or a specific semaphore) could help avoid some more bugs.

Nick Mueller

> I think perhaps BECAUSE spin isn't type-aware, this might be a good thing.

Or that way round.
I use the tags even in type aware-languages to see type-propagation problems. Some compilers aren't picky enough about that.


Nick

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Never use force, just go for a bigger hammer!

The DIY Digital-Readout for mills, lathes etc.:
YADRO

Ken Peterson

The important thing is to pick a style that works for you and be consistent with it. If you find a particular style to be more cumbersome than useful, don't use it. Always try to write code as if someone else is going to have to read it, even if you think no one else will. You might as well be someone else if you're trying to read your own code a few months down the road.