SynthModules

I'm not sure this represents a 'yay' or a 'nay' :)

Problems with standards: one man's meat is another man's poison (or 
as said by an extremely talented singer-songwriter who is nonetheless 
unknown: "One man's verse is another man's prose").  What is 
descriptive to some might not be for others.

ALL CAPS is historical I think (MBASIC anyone? Further back?)

Since I agree with the basic premise, I've coded my stuff to conform 
to what came before me (my consultant background showing).  That way, 
it's at least uniform.

One thing I do strongly agree with is the labelling of global 
variables.  However, in this language EVERY variable is global :( 
What I've done is to indicate where a variable is tweaked elsewhere 
(as in a GOSUB) within the comments.

Mike

--- In SynthModules@yahoogroups.com, "Andrew Scheidler" 
<xpandrew@p...> wrote:
> Conform...  conform!
> 
> I agree 100% on having some standards.  I think it's in all our best
> interests if we're serious about sharing and building a useful 
library
> of programs.
> 
> How about a 5 member program review board.  The individual board 
members
> would examine programs as they are submitted, then they would 
conviene
> on a bi-weekly basis to debate the usefulness, coding and overall 
beauty
> of the programs (intresting LED effects would be given special
> consideration!).  Each program would then be voted on, and those 
that
> receive a majority of board member votes would be posted on the 
Yahoo
> site.  Board member terms would be for 1 year, and elections would 
be
> held on the second Tuesday of July.  PSIM owners would vote by 
recording
> a 56k MP3 of their SpeakJet chip reading the names of the board 
members
> they are voting for.
> 
> Ha ha ha ha.  
> OK, no more Mountain Dew this morning =)
> 
> Andrew
> 
> >>> jmahoney@g... 05/13/04 9:57 AM >>>
> Brice had written:
> > One of these days... I'll take *all* the code offline and fix it 
all
> then
> > re-upload it.
> 
> While I'm going to make some comments below, I'd like you all to
> consider
> this as sort of an opinion poll. Your answers will probably fall 
into 2
> categories: "It ain't broke, don't fix it" and "Yeah, maybe we 
should do
> [something]."
> 
> Before I get started, let me once again say a hearty "Thank you!" to
> those
> trailblazers who have hacked a path through the jungle and -- to mix
> metaphors -- laid a foundation on which we can all build. The 
following
> is
> meant to be constructive, from the viewpoint of someone looking with
> hindsight at the previous work.
> 
> 
> One of the things that strikes me when I review the existing 
programs
> (besides how cool and easy to program the PSIM is) is the variable
> naming.
> Now, I understand that all you "early adopters" have gotten used to
> these
> names. However, we all hope that the future will bring more people 
into
> the
> PSIM fold, so an effort to make the standard names more 
understandable
> may
> be good in the long run.
> 
> 
> I. ALL CAPS
> Why are we using all caps? The language is not case sensitive. Just
> curious.
> 
> 
> II. Designator for common variables
> There are a number of variables that have been defined by Brice, 
Grant,
> Dr
> Mabuse, and others. These are the standard things that we will be 
using
> all
> the time, such as ADC1 and DAC1V. I'm just wondering if it would be
> sensible
> to adopt a prefix (or suffix) to identify them. Perhaps a 
lowercase "g"
> (as
> in "global", although all vars are global) so we would have gADC1 
and
> gDAC1V. Maybe "psim" is a better prefix. (Maybe I should just shut 
up!
> ;-)
> 
> An alternative would be to leave the existing names alone, and use a
> prefix
> on one's own variables: myNote, myLoop. But, one reason to clearly
> identify
> the "standard" vars is so that users know immediately which variable
> names
> should not be changed, because they are used in the common 
subroutines,
> etc.
> Such a convention also helps users avoid stepping on variables used 
in
> the
> low level subroutines. I admit that we are not dealing with large
> programs,
> so I hate to make too much of this.
> 
> 
> III. Names
> Some variables have nice, descriptive names, like STOPLED. On the 
other
> hand, the Stop button is IN5. Why is that?
> 
> And then there are ADC1, DAC1, and DAC1V. What's this about? I know 
that
> the
> inputs are ADCs and outputs are DACs, but the PSIM is labeled IN-1 
thru
> IN-4, and OUT-1 thru OUT-4. Therefore, I suggest that ADC1 would be
> better
> named "In1." DAC1V could be "Out1." Isn't that more intuitive?
> 
> (Or gIn1, gOut1, gDAC1... Gin and gout? I guess those are weird 
looking
> names.)
> 
> As for DAC1, that's fine as-is (or as gDAC1 if we use prefixes). The
> LOADALLDACS routine will move Out1 thru Out4 to DAC1 thru DAC4, but
> that's
> not really user code. I'm not concerned about the var names used in 
low

> level code.
> 
> 
> That's about it. Please try not to flame me too severely if you
> disagree.
> There are some IT pros here, so I'd like to hear what they *and* the
> novice
> programmers have to say.
> 
> Wow, thanks for reading all the way through! :-)
> --
> john
> 
> 
> 
> 
> Be sure to check out the primary Web site at:
> http://www.SynthModules.com
>   
> Yahoo! Groups Links

Conform...  conform!

I agree 100% on having some standards.  I think it's in all our best
interests if we're serious about sharing and building a useful library
of programs.

How about a 5 member program review board.  The individual board members
would examine programs as they are submitted, then they would conviene
on a bi-weekly basis to debate the usefulness, coding and overall beauty
of the programs (intresting LED effects would be given special
consideration!).  Each program would then be voted on, and those that
receive a majority of board member votes would be posted on the Yahoo
site.  Board member terms would be for 1 year, and elections would be
held on the second Tuesday of July.  PSIM owners would vote by recording
a 56k MP3 of their SpeakJet chip reading the names of the board members
they are voting for.

Ha ha ha ha.  
OK, no more Mountain Dew this morning =)

Andrew

>>> jmahoney@gate.net 05/13/04 9:57 AM >>>
Brice had written:
> One of these days... I'll take *all* the code offline and fix it all
then
> re-upload it.

While I'm going to make some comments below, I'd like you all to
consider
this as sort of an opinion poll. Your answers will probably fall into 2
categories: "It ain't broke, don't fix it" and "Yeah, maybe we should do
[something]."

Before I get started, let me once again say a hearty "Thank you!" to
those
trailblazers who have hacked a path through the jungle and -- to mix
metaphors -- laid a foundation on which we can all build. The following
is
meant to be constructive, from the viewpoint of someone looking with
hindsight at the previous work.


One of the things that strikes me when I review the existing programs
(besides how cool and easy to program the PSIM is) is the variable
naming.
Now, I understand that all you "early adopters" have gotten used to
these
names. However, we all hope that the future will bring more people into
the
PSIM fold, so an effort to make the standard names more understandable
may
be good in the long run.


I. ALL CAPS
Why are we using all caps? The language is not case sensitive. Just
curious.


II. Designator for common variables
There are a number of variables that have been defined by Brice, Grant,
Dr
Mabuse, and others. These are the standard things that we will be using
all
the time, such as ADC1 and DAC1V. I'm just wondering if it would be
sensible
to adopt a prefix (or suffix) to identify them. Perhaps a lowercase "g"
(as
in "global", although all vars are global) so we would have gADC1 and
gDAC1V. Maybe "psim" is a better prefix. (Maybe I should just shut up!
;-)

An alternative would be to leave the existing names alone, and use a
prefix
on one's own variables: myNote, myLoop. But, one reason to clearly
identify
the "standard" vars is so that users know immediately which variable
names
should not be changed, because they are used in the common subroutines,
etc.
Such a convention also helps users avoid stepping on variables used in
the
low level subroutines. I admit that we are not dealing with large
programs,
so I hate to make too much of this.


III. Names
Some variables have nice, descriptive names, like STOPLED. On the other
hand, the Stop button is IN5. Why is that?

And then there are ADC1, DAC1, and DAC1V. What's this about? I know that
the
inputs are ADCs and outputs are DACs, but the PSIM is labeled IN-1 thru
IN-4, and OUT-1 thru OUT-4. Therefore, I suggest that ADC1 would be
better
named "In1." DAC1V could be "Out1." Isn't that more intuitive?

(Or gIn1, gOut1, gDAC1... Gin and gout? I guess those are weird looking
names.)

As for DAC1, that's fine as-is (or as gDAC1 if we use prefixes). The
LOADALLDACS routine will move Out1 thru Out4 to DAC1 thru DAC4, but
that's
not really user code. I'm not concerned about the var names used in low
level code.


That's about it. Please try not to flame me too severely if you
disagree.
There are some IT pros here, so I'd like to hear what they *and* the
novice
programmers have to say.

Wow, thanks for reading all the way through! :-)
--
john




Be sure to check out the primary Web site at:
http://www.SynthModules.com
  
Yahoo! Groups Links

> Problems with standards: one man's meat is another man's poison

Agreed, that's why I tossed this out to the group. It needs to simmer for a
few days.


> What is descriptive to some might not be for others.

In some cases, yes. But IN5 v StopButton?

While I'm picking on things, even the name LOADALLDACS is more technical
than it need be. The high level function of this routine is to update the
output CVs with the values in the output variables, so it's a
"WriteAllOutputs" routine. Since there are also routines that update only
one DAC, these could be called WriteOutput1 thru WriteOutput4, and thus
LOADALLDACS might be named WriteOutputsAll (cumbersome) or even
WriteOutputs1to4 (in case a future PSIM has, say, a WriteOutputs1to8
routine, you know?).

Maybe the word "Write" is also too technical, and I should say "Send," but I
think that Read and Write are more descriptive than SCAN and LOAD. (What's
the opposite of Send? Receive? No thanks. Read & Write seem better to me.
But it's quite subjective, I know!)


> ALL CAPS is historical I think (MBASIC anyone? Further back?)

And of minor importance, since the compiler doesn't care. ALL CAPS ARE FINE.
;-) For what it's worth, all caps goes back decades. Computers used nothing
but caps for many years before they could handle lowercase.


> Since I agree with the basic premise, I've coded my stuff to conform
> to what came before me (my consultant background showing).  That way,
> it's at least uniform.

For sure, we should try to conform to the same standards. I wasn't picking
on anyone's code.


> One thing I do strongly agree with is the labelling of global
> variables.  However, in this language EVERY variable is global :(
> What I've done is to indicate where a variable is tweaked elsewhere
> (as in a GOSUB) within the comments.

I know. All variables are global, but some are more global than others. (Ha
ha, I'm paraphrasing a famous quote there.)

So, the word "global" is not the best way to describe the common variables,
but... Hey! How about "c" for "common"?

I'm just trying to distinguish between what I'll call "user variables" and
the common, do-not-touch-because-they-belong-to-the-subroutines vars.

Time for me to be quiet so others can weigh in.
--
john

Perhaps we might find it useful to build a document for the group 
(posted) that would list "reserved variables" for lack of a better term. 
This would include the variable name, it's function and the routine(s) 
to which it is passed and used.

Scott E.
--------------------------------------------------------------
Mike Marsh wrote:

> 
> One thing I do strongly agree with is the labelling of global 
> variables.  However, in this language EVERY variable is global :( 
> What I've done is to indicate where a variable is tweaked elsewhere 
> (as in a GOSUB) within the comments.
> 
> Mike