The content of the documentation using the AutoDoc program is entirely up to the program's author. There is no facility in the program to infer that DisplayValue, for example, displays a value. The objective of the AutoDoc program is to format code and comments in such a way that the purpose and use of the program are easy to access and understand, but without cluttering the code itself with too many cryptic tags or distracting formatting cues. So there's no inherent reason that an AutoDoc'd program cannot read like any other prosaic documentation.
No one (in their right mind, anyway) truly enjoys writing program documentation. The advantage of autodocumented code is that, if it makes documentation easier for the author to write and format, it's more likely to get done in the first place. To that end, I've extended the AutoDoc program to take undocumented code and add the AutoDoc-compatible boilerplate, so that the programmer need only fill in the blanks.
I will admit, however, that some programmers may be entranced so by the pretty formatting that they neglect the task of clear exposition. There's nothing that I, or anyone else, can do about that.
-Phil
Phil, I wasn't putting down the documenting tool, I think it's actually pretty cool.
I understand that the user has to put in the definitions, it's just that the programmer probably isn't the proper person to do that.
Maybe having the programmer do the first pass and then a tech writter type person could go back over the source and embellish the comments added by the programmer.
It's similar to having another person review the code because too many things seem obvious to the person that wrote the initial code.
I've become pretty jaded on MS help as it seems most msdn documents leave me saying "No $^%& Sherlock, I could see that from the method signature, but how the $#%^ do I use it."
...besides standardizing process, code style, documentation etc. it seems like someone needs to standardize driver interface/protocol/naming - want to be able to do stuff like...
display.char() ' where display can be PST, UART, VGA, LCD, 7-seg, etc.
adc.in ' where adc can be various chips, software adc
serial_periph.writebyte() 'where serial_periph can be I2C, SPI, 1-Wire
I've become pretty jaded on MS help as it seems most msdn documents leave me saying "No $^%& Sherlock, I could see that from the method signature, but how the $#%^ do I use it."
This is always an issue and, IMO, beyond the scope of a Gold Standard. For example, FDS has nothing to do with a proprietary device protocol.
I believe we are having this discussion because the Gold Standard process became overly complex. A great idea bogged down by twenty seven eight-by-ten color glossy pictures with circles and arrows and a paragraph on the back of each one. Alice's Restaurant by Arlo Guthrie
A Gold Standard should be driven by business needs.
I was on the committee too, we have a draft spec all edited and ready to go, but documentation (javadoc style) was an issue. I reached out to Phil to modify his spin documentor, however I don't think much came of that. My perspective is that trying something is better than sitting on your hands. I'd like to see the existing process released and see where it goes with the community. I'm pressed for time, maybe more later.
I reached out to Phil to modify his spin documentor, however I don't think much came of that.
I'm not necessarily opposed to doing that, within reason, but support for adoption of the AutoDoc program and any mods to it has to come directly from Parallax.
Phil, I can't speak for Parallax, but after you read the above doc, I hope you will pick up the torch and run with it.
Please note that 'SpinDoc' is loosely defined on purpose, the exact syntax and layout of Javadoc style tags, combined with current SPIN syntax, needs to be worked out. I think example code is best, with it split up into sections and annotated.
Phil, I can't speak for Parallax, but after you read the above doc, I hope you will pick up the torch and run with it.
At this point, I've done all I'm going to do until I get a thumbs up from Parallax. I've got other projects to attend to and don't wish to invest more time in something that may not ultimately bear fruit.
Interesting,
about 18 different posters here since I opened the "Top 5" thread, but only 4 people bothered to post a suggestion.
Documentation and process is apparently more interesting to discuss.
I'm working for a large medical HMO right now, and spend ~75% of my time on process, change management, etc.
While it has its place, and is necessary, I fail to see why there is such a clamoring for this and that...
Decide on some objects, ping the original author and see if he/she wants to help try and take a first stap at getting it GSL'd.
Format your code in a doc, comment on compiled size, memory used, and arguments to supply and return values expected.
Come on, this is like CS-101 level here.
If we even get this far with several objects, THEN consideration could be given to upping the formatting.
Otherwise, this is going to get no further than the last iteration.
The main "issue" that I have with Autodoc is that it doesn't have a standard format for the documentation, it has a standard format for it's presentation. It's perfect for having control over how your documentation is presented, but it doesn't set a standard for how all code should be documented. That's is an issue for a standard library.
No one (in their right mind, anyway) truly enjoys writing program documentation.
I seldom disagree with Phil but I must say this is a poor choice of words. It should be rephrased to say:
"No one (in their right mind, anyway) truly enjoys going back over crappy code and trying to figure out what the h311 it was supposed to do."
If the code is written properly, we can look back at it and read what it say without a lot of guessing. If its not, we probably can't and it probably doesn't do what we think it does anyway. And then we notice its got errors and we have to fix them and go through the cycle yet again. This is what makes it painful and expensive.
There's nothing that I, or anyone else, can do about that.
Actually, there i s quite a lot we can do about it, and the data shows its very effective (and personal experience shows it makes life easier all the way around). But the misconception stands in the way.
If the code is written properly, we can look back at it and read what it say without a lot of guessing
Except if it written in Forth of course:)
Sorry, just kidding, I'm still butting by head on that nut.
Anyway, this is all positive. We have a clean slate. The code can be written "properly" from the get go.
You see, as stated by myself and others many times, there is no place in the Gold Standard of Parallax Semiconductor for Spin code. It's useless for the intended market or audience. I would say it is even detrimental to prospects.
If the code is crappy then why waste time running it through the goldification process?
Since you asked:
The RIGOR of code development is the same, whether FDA/FAA regulated, professional, or hobbyist; to achieve stable, reliable code. The PAPERWORK required for regulated industries is excessive, because there's some bozo that will say "working or not, get it out the door NOW!" and somebody could get killed. If we ignore the required rigor, it is less likely that we will arrive at the code we want. The distinction is between paperwork and engineering, we want to eliminate excessive paperwork, but we cannot skip the engineering.
The reason why the Gold Standard is not progressing is because the qualification for the Gold Standard have not been defined to any degree that we can confirm or deny a particular item as "meeting the standard". This is due to misunderstanding the above.
Stable reliable code is achieved by having:
1) clear requirements as to what the code is intended to to do, to the extent that one may determine, yes or no, whether the code actually achieves that purpose.
2) Tests that actually measure the presence or absence of the required functions, and answer the degree or condition under which each function does or does not fulfill its function.
3) code that implements those functions
4) Evidence that shows the tests were performed on the specific set of code in question, and clearly shows the result of each test to confirm or deny that each function performs are stated.
We can do these in the order stated (this is how experinced professionals do it), or we can "code first, debug forever" (which is how the hacks do it), or anywhere in between. Please note that the primary difference between the professionals and the hacks is the recognition that preliminary experiments are in the investigation phase, and are separate from final code.
In any case, the process is conducted with one or more iterations: Plan the requirements, plan the tests, write the code, perform the tests, evaluate, repeat until satisfied. Doing the step in order listed usually requires fewer steps; doing the steps in a different order usually requires significantly more steps. Examples to the contrary are rare or more typically incorrectly reported.
We are free to do anything we want according to our situation of what a given task calls for. The idea behind process (in this case software development life-cycle process) is to establish a common method and terminology so we can ensure that the best practice behaviors are preformed where required.
In any case, code is the easiest, smallest part of any project. Planning and organization is the majority of the engineering of any project.
Lets look at a couple examples: Kye's SD FAT support, and the Prop GCC compiler. These did not start with random people writing a bunch of code, and a working result appeared by magic. On the contrary, very qualified individuals took steps to ensure that the material conforms with applicable standards. They performed rigorous testing. They invited review. The responded to issues. They evaluated whether each report was a valid issue or not. They decided to act on each issue or not. They allowed the reporting party to response that the issue is addressed or not. The process is iterative over an extended time, and is ongoing. We notice that as more issues are addressed, fewer issues are reported.
We want to capture the behaviors that we performed on these projects. If folks can reproduce this process, then there is a higher likelihood that the results would be of similar quality. We want to identify if folks deviate from the process. This is to identify deficiencies with the result, or with the process. (If somebody discovers an easier way, then we all want to hear about it). The folks that do these behaviors typically do them unconsciously by virtue of discipline, therefore it is difficult to identify and teach the most beneficial behaviors (and avoid any quirky, non beneficial behaviors). This is why we want to record a process.
After sufficient effort, ANY item can qualify as meeting such a standard. But we can also determine which items are not worth additional effort; perhaps they will not be widely used or the basic concept is flawed. We want to identify this as early as possible.
Defining and setting up the Gold Standard would be pretty easy, refining it would take a little time but its doable. As always, the main hurdle is educating the participants as to what its about and why its a good idea.
The only way what you suggest will work is to use professional programmers who are used to working in such teams and understand the disciplines of which you write. Plus familiarity with the latest project management and software tools. You can't have some poor self-taught schmuck whose idea of software engineering is Spin. It will also have to be headed up by a competent project manager with a proven record of getting projects done.
It won't be cheap and probably take several years.
Ummm... No I asked, If the code is crappy then why waste time running it through the goldification process?
Thanks for the commentary on the SDLC.
If you apply the process (check requirements, ensure test coverage, and perform peer review) it would not be crappy in the first place. AT least it would be much less likely to be deficient for want of obvious behaviors.
The only way what you suggest will work is to use professional programmers who are used to working in such teams and understand the disciplines of which you write. Plus familiarity with the latest project management and software tools. You can't have some poor self-taught schmuck whose idea of software engineering is Spin.
Of course we can. The only difference between an engineer and a hacker is training and habits. And we often see the title of engineer is also awarded to those with poor training and habits, so the self taught are often of a higher caliber.
It won't be cheap and probably take several years.
It won't cost anything except time and effort, and its going to take years in any case. Unless you have some solution that we can put in place tomorrow, there's still no valid case against.
If it takes 5 years to learn Japanese and you start today, it'll take 5 years. If you wait 10 years before you get started, it will take 15 years.
I think that structure and process doesn't make good code, it makes code that passes a process test.
Good code is born from good programmers, you will never get around that. Where the very limited framework we authored comes in is to give good code all of the chrome and polish it needs to be accepted into the GSL repository, it's not a substitute for good code.
You can write absolute shite and have it pass the process, but a seasoned developer will look at the code and say "huh?!"
It is futile IMHO to engineer process any more than what we have already, the ball has to make it down the field with human hands, so after the initial weeding process you need a seasoned human to review the code and decide subjectively whether it passes their muster and how to classify it.
Also, the "many hands make light work" is proven to be a fallacy in software development, the quality of the review depends on the quality of the reviewer. If you have a bunch of low to mid grade developers reviewing sophisticated code, the subtle errors will never be fixed because they don't grok it.
This is where Benevolent Dictatorship comes into play, you need to have a seasoned developer with good instincts to act as an escalation end-point, make crucial decisions, and act as ultimate arbiter.
For me personally, the gold standard was the most help as a list of guidelines when starting a new project (FFDS1). It did not change how I code (algorithms), at all, but it did make all the easy decisions for me like how to name routines, things like that. If you compare FFDS1 with F32, you will quickly see differences. [8^)
I believe that implementing the standard in more 'objects' (and code in general) will have the benefit to the users of instantly helping them know "that's a constant", "that's a function name", etc. It just makes the code more readable. I don't believe I have ever used some OBEX code without making some changes, so the readability / standardization aspect is the most important one to me.
For newcomers, of course, being able to actually use the object out of the box is critical. [8^)
Now, if I had to vote on a benevolent dictator (?), I would vote for kuroneko, and ask Parallax to pay him some amount per gold object committed. (After all, only in the fairy tales can you spin straw into Gold Standard software for free.)
Guys.
I fail to see what the problem is here.
My steps clearly state that step3 is that the code must get a certain amount of nominations before it's even elegible for gold standard process. This step all by itself will remove any (if not all) crappy code (as it has been put) Why? Because nobody is going to suggest that a piece of crappy code gets promoted to gold status consideration.
Where's the problem here?
Also, one of the steps is to determine if the object is useful for the gold standard (remember the part about nobody wanting a hello world program in the gold library?)
All the negative posts here are referring to things that aren't even part of the process. If you're suggesting they should be, then that's a different discussion, though I'd not volunteer to champion such things myself).
Come on folks, take a look at the steps, and let me know what (if anything) was left out. In a couple weeks, I can easily starting coding a php site that will show all the objects (drawn directly from parallax's site) then add buttons for nomination if anyone thinks it's worhtwhile.
I realize many here don't think an effort of this sort is worth doing, but most of those same people are the ones complaining about bad and useless code, which to me doesn't make much sense.
Even if an effort like this isn't promoted/supported/participated in by Parallax, it's still something the community will benefit from, so (imo) it's still worth doing. This is really no different than sites that evaluate software, and publish their findings to determine if that software is worth using or not. Sure, the whole process can't be completed without Parallax help (I.E. hosting the final gold objects when they're completed) but there's nothing that says it can't be carried through to it's logical conclusion anyway. If Parallax blessing is not forthcoming for whatever reason, then there's still nothing stopping someone (anyone) from making their own archive hosting code that is the best of the best based on user feedback. Again, this is nothing different than sites like versiontracker. Heck, if it comes down to it, there's nothing preventing someone from taking every single object, rewriting it, and reposting it anywhere they like, that's the whole point of the mit license. This is a project that can be carried out with or without parallax support. Sure, having parallax bless the project would be useful, but as we all know, in the world of software, there's nothing preventing someone from doing any of the things mentioned above.
So,, let's go on the assumption that someone (either me or someone else) will take on the roll of coordinator, and talk about what we can do to make that process work better.
Talk about what makes an object a good one, and talk about what would be useful things for objects to have, even if they're not mandatory for whatever label we'd like to slap on the code, even if it's not gold standard, perhaps it's community verified. Who cares what it's called, the point is lots of people say the obex needs help. I'm offering that help.
Whether the final product is to be hosted on parallax, or elsewhere is immaterial at this point. Now, all that's needed is ironing out of what constitutes the proces of determining quality code.
For me personally, the gold standard was the most help as a list of guidelines when starting a new project (FFDS1). It did not change how I code (algorithms), at all, but it did make all the easy decisions for me like how to name routines, things like that. If you compare FFDS1 with F32, you will quickly see differences. [8^)
I believe that implementing the standard in more 'objects' (and code in general) will have the benefit to the users of instantly helping them know "that's a constant", "that's a function name", etc. It just makes the code more readable. I don't believe I have ever used some OBEX code without making some changes, so the readability / standardization aspect is the most important one to me.
For newcomers, of course, being able to actually use the object out of the box is critical. [8^)
Now, if I had to vote on a benevolent dictator (?), I would vote for kuroneko, and ask Parallax to pay him some amount per gold object committed. (After all, only in the fairy tales can you spin straw into Gold Standard software for free.)
Here's what I think I will do: I'll start a PropGCC C++ library of objects. This library will be hosted as part of Google Code, and will include things such as FSRW, FFDS1, keyboard and mouse, VGA, etc. The objects will all have CppUTest unit test frameworks to test as much of the code*, and verify/document correct operation.
*That is if I can get it working
Some may notice that this overlaps with the PropGCC efforts. I.e., why have FSRW and FFDS1 and <BLANK> when such is available as part of GCC? Because those standard functions come with the performance/size hit necessary to comply with the C standards. Which is fine for C programmers from elsewhere, but I want the comfort of control.
I'm currently being contracted to work on some Propeller firmware for a product, and at the end we're going to open source it all. So, it should provide a nice little library to start with. And if the community doesn't use it, that's ok too: it's no different than what I would do for my own personal library.
...I was going to say that while Parallax has to drive & own a 'Parallax Gold Standard' (which doesn't mean Parallax employees have to do the work per se), there's nothing to prevent anybody from making & hosting 'Joes Gold Standard'. That's good and the more the merrier - indeed multiple efforts over time would allow the users to vote on the best scheme (process, coding, testing, doc) with their download clicks. Perhaps then the 'winning' approach can be used as a model or otherwise morphed, with Parallax blessing, into the official 'Parallax Gold Standard'. The alternative seems to be do nothing until a) everyone agrees on everything and b) Parallax has $$$ to 'drive & own', both of which might take awhile. Instead any so-minded Joe(s) can get started today!
I'm currently being contracted to work on some Propeller firmware for a product, and at the end we're going to open source it all. So, it should provide a nice little library to start with.
This is a big deal, it should more things forward greatly. Very glad to hear this in on the way.
...I was going to say that while Parallax has to drive & own a 'Parallax Gold Standard' (which doesn't mean Parallax employees have to do the work per se), there's nothing to prevent anybody from making & hosting 'Joes Gold Standard'. That's good and the more the merrier - indeed multiple efforts over time would allow the users to vote on the best scheme (process, coding, testing, doc) with their download clicks. Perhaps then the 'winning' approach can be used as a model or otherwise morphed, with Parallax blessing, into the official 'Parallax Gold Standard'. The alternative seems to be do nothing until a) everyone agrees on everything and b) Parallax has $$$ to 'drive & own', both of which might take awhile. Instead any so-minded Joe(s) can get started today!
Comments
Phil, I wasn't putting down the documenting tool, I think it's actually pretty cool.
I understand that the user has to put in the definitions, it's just that the programmer probably isn't the proper person to do that.
Maybe having the programmer do the first pass and then a tech writter type person could go back over the source and embellish the comments added by the programmer.
It's similar to having another person review the code because too many things seem obvious to the person that wrote the initial code.
I've become pretty jaded on MS help as it seems most msdn documents leave me saying "No $^%& Sherlock, I could see that from the method signature, but how the $#%^ do I use it."
C.W.
display.char() ' where display can be PST, UART, VGA, LCD, 7-seg, etc.
adc.in ' where adc can be various chips, software adc
serial_periph.writebyte() 'where serial_periph can be I2C, SPI, 1-Wire
I believe we are having this discussion because the Gold Standard process became overly complex. A great idea bogged down by twenty seven eight-by-ten color glossy pictures with circles and arrows and a paragraph on the back of each one. Alice's Restaurant by Arlo Guthrie
A Gold Standard should be driven by business needs.
-Phil
Phil, I can't speak for Parallax, but after you read the above doc, I hope you will pick up the torch and run with it.
Please note that 'SpinDoc' is loosely defined on purpose, the exact syntax and layout of Javadoc style tags, combined with current SPIN syntax, needs to be worked out. I think example code is best, with it split up into sections and annotated.
-Phil
about 18 different posters here since I opened the "Top 5" thread, but only 4 people bothered to post a suggestion.
Documentation and process is apparently more interesting to discuss.
I'm working for a large medical HMO right now, and spend ~75% of my time on process, change management, etc.
While it has its place, and is necessary, I fail to see why there is such a clamoring for this and that...
Decide on some objects, ping the original author and see if he/she wants to help try and take a first stap at getting it GSL'd.
Format your code in a doc, comment on compiled size, memory used, and arguments to supply and return values expected.
Come on, this is like CS-101 level here.
If we even get this far with several objects, THEN consideration could be given to upping the formatting.
Otherwise, this is going to get no further than the last iteration.
The main "issue" that I have with Autodoc is that it doesn't have a standard format for the documentation, it has a standard format for it's presentation. It's perfect for having control over how your documentation is presented, but it doesn't set a standard for how all code should be documented. That's is an issue for a standard library.
I seldom disagree with Phil but I must say this is a poor choice of words. It should be rephrased to say:
"No one (in their right mind, anyway) truly enjoys going back over crappy code and trying to figure out what the h311 it was supposed to do."
If the code is written properly, we can look back at it and read what it say without a lot of guessing. If its not, we probably can't and it probably doesn't do what we think it does anyway. And then we notice its got errors and we have to fix them and go through the cycle yet again. This is what makes it painful and expensive.
Actually, there i s quite a lot we can do about it, and the data shows its very effective (and personal experience shows it makes life easier all the way around). But the misconception stands in the way.
Sorry, just kidding, I'm still butting by head on that nut.
Anyway, this is all positive. We have a clean slate. The code can be written "properly" from the get go.
You see, as stated by myself and others many times, there is no place in the Gold Standard of Parallax Semiconductor for Spin code. It's useless for the intended market or audience. I would say it is even detrimental to prospects.
So, who is going to do that?
Since you asked:
The RIGOR of code development is the same, whether FDA/FAA regulated, professional, or hobbyist; to achieve stable, reliable code. The PAPERWORK required for regulated industries is excessive, because there's some bozo that will say "working or not, get it out the door NOW!" and somebody could get killed. If we ignore the required rigor, it is less likely that we will arrive at the code we want. The distinction is between paperwork and engineering, we want to eliminate excessive paperwork, but we cannot skip the engineering.
The reason why the Gold Standard is not progressing is because the qualification for the Gold Standard have not been defined to any degree that we can confirm or deny a particular item as "meeting the standard". This is due to misunderstanding the above.
Stable reliable code is achieved by having:
1) clear requirements as to what the code is intended to to do, to the extent that one may determine, yes or no, whether the code actually achieves that purpose.
2) Tests that actually measure the presence or absence of the required functions, and answer the degree or condition under which each function does or does not fulfill its function.
3) code that implements those functions
4) Evidence that shows the tests were performed on the specific set of code in question, and clearly shows the result of each test to confirm or deny that each function performs are stated.
We can do these in the order stated (this is how experinced professionals do it), or we can "code first, debug forever" (which is how the hacks do it), or anywhere in between. Please note that the primary difference between the professionals and the hacks is the recognition that preliminary experiments are in the investigation phase, and are separate from final code.
In any case, the process is conducted with one or more iterations: Plan the requirements, plan the tests, write the code, perform the tests, evaluate, repeat until satisfied. Doing the step in order listed usually requires fewer steps; doing the steps in a different order usually requires significantly more steps. Examples to the contrary are rare or more typically incorrectly reported.
We are free to do anything we want according to our situation of what a given task calls for. The idea behind process (in this case software development life-cycle process) is to establish a common method and terminology so we can ensure that the best practice behaviors are preformed where required.
In any case, code is the easiest, smallest part of any project. Planning and organization is the majority of the engineering of any project.
Lets look at a couple examples: Kye's SD FAT support, and the Prop GCC compiler. These did not start with random people writing a bunch of code, and a working result appeared by magic. On the contrary, very qualified individuals took steps to ensure that the material conforms with applicable standards. They performed rigorous testing. They invited review. The responded to issues. They evaluated whether each report was a valid issue or not. They decided to act on each issue or not. They allowed the reporting party to response that the issue is addressed or not. The process is iterative over an extended time, and is ongoing. We notice that as more issues are addressed, fewer issues are reported.
We want to capture the behaviors that we performed on these projects. If folks can reproduce this process, then there is a higher likelihood that the results would be of similar quality. We want to identify if folks deviate from the process. This is to identify deficiencies with the result, or with the process. (If somebody discovers an easier way, then we all want to hear about it). The folks that do these behaviors typically do them unconsciously by virtue of discipline, therefore it is difficult to identify and teach the most beneficial behaviors (and avoid any quirky, non beneficial behaviors). This is why we want to record a process.
After sufficient effort, ANY item can qualify as meeting such a standard. But we can also determine which items are not worth additional effort; perhaps they will not be widely used or the basic concept is flawed. We want to identify this as early as possible.
Defining and setting up the Gold Standard would be pretty easy, refining it would take a little time but its doable. As always, the main hurdle is educating the participants as to what its about and why its a good idea.
Thanks for the commentary on the SDLC.
The only way what you suggest will work is to use professional programmers who are used to working in such teams and understand the disciplines of which you write. Plus familiarity with the latest project management and software tools. You can't have some poor self-taught schmuck whose idea of software engineering is Spin. It will also have to be headed up by a competent project manager with a proven record of getting projects done.
It won't be cheap and probably take several years.
If you apply the process (check requirements, ensure test coverage, and perform peer review) it would not be crappy in the first place. AT least it would be much less likely to be deficient for want of obvious behaviors.
Of course we can. The only difference between an engineer and a hacker is training and habits. And we often see the title of engineer is also awarded to those with poor training and habits, so the self taught are often of a higher caliber.
It won't cost anything except time and effort, and its going to take years in any case. Unless you have some solution that we can put in place tomorrow, there's still no valid case against.
If it takes 5 years to learn Japanese and you start today, it'll take 5 years. If you wait 10 years before you get started, it will take 15 years.
Good code is born from good programmers, you will never get around that. Where the very limited framework we authored comes in is to give good code all of the chrome and polish it needs to be accepted into the GSL repository, it's not a substitute for good code.
You can write absolute shite and have it pass the process, but a seasoned developer will look at the code and say "huh?!"
It is futile IMHO to engineer process any more than what we have already, the ball has to make it down the field with human hands, so after the initial weeding process you need a seasoned human to review the code and decide subjectively whether it passes their muster and how to classify it.
Also, the "many hands make light work" is proven to be a fallacy in software development, the quality of the review depends on the quality of the reviewer. If you have a bunch of low to mid grade developers reviewing sophisticated code, the subtle errors will never be fixed because they don't grok it.
This is where Benevolent Dictatorship comes into play, you need to have a seasoned developer with good instincts to act as an escalation end-point, make crucial decisions, and act as ultimate arbiter.
I believe that implementing the standard in more 'objects' (and code in general) will have the benefit to the users of instantly helping them know "that's a constant", "that's a function name", etc. It just makes the code more readable. I don't believe I have ever used some OBEX code without making some changes, so the readability / standardization aspect is the most important one to me.
For newcomers, of course, being able to actually use the object out of the box is critical. [8^)
Now, if I had to vote on a benevolent dictator (?), I would vote for kuroneko, and ask Parallax to pay him some amount per gold object committed. (After all, only in the fairy tales can you spin straw into Gold Standard software for free.)
Jonathan
I fail to see what the problem is here.
My steps clearly state that step3 is that the code must get a certain amount of nominations before it's even elegible for gold standard process. This step all by itself will remove any (if not all) crappy code (as it has been put) Why? Because nobody is going to suggest that a piece of crappy code gets promoted to gold status consideration.
Where's the problem here?
Also, one of the steps is to determine if the object is useful for the gold standard (remember the part about nobody wanting a hello world program in the gold library?)
All the negative posts here are referring to things that aren't even part of the process. If you're suggesting they should be, then that's a different discussion, though I'd not volunteer to champion such things myself).
Come on folks, take a look at the steps, and let me know what (if anything) was left out. In a couple weeks, I can easily starting coding a php site that will show all the objects (drawn directly from parallax's site) then add buttons for nomination if anyone thinks it's worhtwhile.
I realize many here don't think an effort of this sort is worth doing, but most of those same people are the ones complaining about bad and useless code, which to me doesn't make much sense.
Even if an effort like this isn't promoted/supported/participated in by Parallax, it's still something the community will benefit from, so (imo) it's still worth doing. This is really no different than sites that evaluate software, and publish their findings to determine if that software is worth using or not. Sure, the whole process can't be completed without Parallax help (I.E. hosting the final gold objects when they're completed) but there's nothing that says it can't be carried through to it's logical conclusion anyway. If Parallax blessing is not forthcoming for whatever reason, then there's still nothing stopping someone (anyone) from making their own archive hosting code that is the best of the best based on user feedback. Again, this is nothing different than sites like versiontracker. Heck, if it comes down to it, there's nothing preventing someone from taking every single object, rewriting it, and reposting it anywhere they like, that's the whole point of the mit license. This is a project that can be carried out with or without parallax support. Sure, having parallax bless the project would be useful, but as we all know, in the world of software, there's nothing preventing someone from doing any of the things mentioned above.
So,, let's go on the assumption that someone (either me or someone else) will take on the roll of coordinator, and talk about what we can do to make that process work better.
Talk about what makes an object a good one, and talk about what would be useful things for objects to have, even if they're not mandatory for whatever label we'd like to slap on the code, even if it's not gold standard, perhaps it's community verified. Who cares what it's called, the point is lots of people say the obex needs help. I'm offering that help.
Whether the final product is to be hosted on parallax, or elsewhere is immaterial at this point. Now, all that's needed is ironing out of what constitutes the proces of determining quality code.
Second the nomination...
*That is if I can get it working
Some may notice that this overlaps with the PropGCC efforts. I.e., why have FSRW and FFDS1 and <BLANK> when such is available as part of GCC? Because those standard functions come with the performance/size hit necessary to comply with the C standards. Which is fine for C programmers from elsewhere, but I want the comfort of control.
I'm currently being contracted to work on some Propeller firmware for a product, and at the end we're going to open source it all. So, it should provide a nice little library to start with. And if the community doesn't use it, that's ok too: it's no different than what I would do for my own personal library.
This is a big deal, it should more things forward greatly. Very glad to hear this in on the way.
How about any so-minded SRLM(s)?
And just as a reminder to all: my efforts are now focusing or PropGCC, not Spin.
So, I just did that. Please see Alex's Parallax Gold Standard attempt.
I have started a new thread for "support" for this website.