No need for Git or SVN. There aren't that many virtual peripherals out there, especially written in C, which is the what the commercial world looks at, not a proprietary interpretive language like Spin.
Look how Cypress handles it's virtual peripheral library for the PSOC5. It's simple and straight forward. Each one is documented like a real world device. All Parallax has to do is come up up with say a dozen reference peripherals, document them and create a dozen projects ranging from industrial to medical that utilize them.
But all this has to be driven by Parallax, not some group of enthusiasts. The software has to be endorsed and supported by Parallax.
I'm a casual Parallaxian, but I have a lot of experience in the MCU biz. rod1963 prompted me to jump in...
1. There are good arguments both ways about soft vs. hard peripherals. But having chosen the soft-peripheral approach, the Prop is really at a disadvantage if it doesn't have standard soft peripherals which (as much as possible) work as well/easily as MCU hard peripherals.
2. The OBEX is fine and so is improving it. But it doesn't really replace the need for Gold Standard #1. Process and standards are important, but the real issue is control, ownership and ultimate responsibility.
All Parallax has to do is come up up with say a dozen reference peripherals, document them and create a dozen projects ranging from industrial to medical that utilize them
.
...I agree, but would just say it isn't as easy ($$$) as it sounds. Truly full 'Test', 'Verification', 'Characterization', 'Documentation', 'Support' is a lot of work, even for something simple like an I2C or UART. Big IC companies can afford it, but non-trivial for Parallax.
Seems really hard to proceed with Gold Standard unless/until Parallax has some $$$ to own it - and they've got a lot on their plate with P2, GCC, etc.
Coming up with reference designs is what companies are supposed to do if they want to market a new micro controller to the commercial sector. They are in a way a sales pitch to engineering professionals, I can easily think of a dozen projects to demonstrate and teach people about the Prop and so can anyone here. Some here are really good at it.
If Parallax can't afford that, then they shouldn't play in the commercial field at all.
Nor is there nothing that stops Parallax from asking some of the Prop experts here for their input for such reference designs. I'm sure most of them would be happy to contribute ideas and software.
And in terms of software. It just means well documented and tested virtual peripherals in C/PASM and not that many, just a dozen or so. Nothing fancy, just a set of drivers like IC2, SPI, Video, maybe a couple of digital filters, a PID loop, etc. For Parallax, they just have to make sure their Gold standard set of virtual peripherals work reliably and be well documented so others can make a informed decision about whether or not to use the Prop.
...another quick thought. a set of quality (tested, documented, supported) soft-peripherals with ease of use and interoperability would be welcome for P1, even at this late date. But in terms of 'commercial' applications P1 has always had a major limitation in lack of code protection. So I think P2 needs this even more than P1, still time to try to figure it out. Maybe for now have a two-tier OBEX for P2 and only let the people who have shown 'Gold Standard' interest and capability allowed to bless stuff for the 'top-tier'. Then what's hashed out and learned in populating this 'Silver Standard' (i.e. interop standards, testing, documentation) can be carried forward to a 'Gold Standard' when Parallax has resources.
A conventional recommendation might be Parallax raise some cash to fund it - but they aren't conventional which is why everyone here loves them.
Easy solution. Send me one of everything parallax sells, and I'll write the gold standard objects for them.
Ok, I'm just being silly, because I am terrible at documentation. Writing code is what I like to do, but writing clean, formatted, well documented code? That's a whole different issue. I suspect others are the same.
What's needed is an approach that incorporates several of the suggestions in this thread. Feel free to amend/suggest where necessary.
1. code gets submitted to the obex.
(this already happens.
2. Code is used by others.
(this already happens.
3. If someone likes the code, they click the button to add a vote for gold standard library inclusion.
4. After x number of promotion clicks
(preferrably by folks who have been members for more than 30 days or so), then it gets raised as a flag for someone to look at.
5. The group of folks who look at the code are wide and varied, and as long as some percentage of those folks (say 25%) think it's good enough, the code then gets promoted again to some other status (pending gold standard maybe?)
6. A group of folks are selected to perform the goldification process, which would include documentation, formatting, whatever else is necessary)
7. code is checked by others (not any of those who already participated in previous rounds) again to verify it meets whatever requirements there may be for final acceptance.
8. if all conditions are met, then code is inducted into the gold standard library, and there is much rejoycing.
Obviously, there's plenty of fleshing out necessary in this process, but much of this work can be done automatically, and some of it can be done by folks who aren't experts on the objects, because experts on software aren't necessary to verify formatting just for example.
Obviously, the higher up the chain the code goes, the less folks there will be with the required skills to pass it through the process, but hopefully, this won't matter, because objects will be filtering through at all levels at any given time, so there will be no lack of work for those who want it.
There should probably be a preliminary step 0 to identify if this code should be included into the gold library at all, for example, nobody needs hello world code in a gold standards library, but that's not to say simple things shouldn't or couldn't be included, some kind of determination would have to be made before it gets voted through step 1.
Coding for buttons to automate most of the process (nominating for gold standard library status, checking formatting, and so on) would be easy to write since php is the language of choice these days for projects like this, and I'm sure there's several forum members besides myself who have experience in php coding, so it would certainly be possible to make the process as streamlined as it can, but still leave room for improvement if process seems to break down during any given stage.
There's an example of this sort of thing that takes place on distributed proofreaders. Books are scanned into the computer (this is for public domain books) The book then goes through as many as 6 levels of proofing/formatting/checking (but never less than 3) before it's deemed complete, and is sent off to project gutenberg for inclusion in their catalog.
It's a process that works well, and has been working well for many years.
I see no reason why something similar couldn't be put in place here to make obex objects into gold standard library objects.
When I worked at CSC, they followed the cmm standard, code wasn't allowed into the production system until it had undergone several levels of peer review, checklist passing, document writing, testing and all kinds of things before it was allowed to be imported into the production system. At times, it was an extremely frustrating process, but as a result, after this process was implemented, production system errors dropped to a very small percentage of what they had been before the system was put in place.
So, in short, I'm simply saying it's certainly possible, many think it's necessary, and I see no reason not to do it.
It will be work for sure, but in the end, we'll all benefit from it, and as a result, there will be greater selection for those hunting for code to help with particular tasks.
It may be a big job, but I'm perfectly willing to take up as much slack as I can to make this happen, and that includes building php database interfaces, making mysql databases, helping write the documents that get used during the process, and maybe even participate in the process when it's all done and tested to completion. As I pointed out above, documentation and pretty code isn't my forte, but enough people believe this is necessary, and I like parallax enough that I'm willing to step up and do what I can to make it happen, so feel free to let me know what I've missed here. There's enough of us that the process shouldn't be a major burden on anyone, though it will take time. I think it can be done though, so whoever wants to help, let me know what parts need changed, and I'll update the steps above accordingly. This should at least get the ball rolling, after that, we can work with what comes next.
6. A group of folks are selected to perform the goldification process, which would include documentation, formatting, whatever else is necessary
Sorry, but I believe the "goldification" needs to be done by the original author. Who but that one person understands the code well enough to perform such a task? IMO, it would be an imposition to relegate that job to others. That being the case, the onus should be on Parallax to make that process as painless as possible. (But I won't comment further, since I still have a dog in that part of the show. )
Sorry, but I believe the "goldification" needs to be done by the original author. Who but that one person understands the code well enough to perform such a task?
Phil. While I understand where you're coming from, in this case, I strongly disagree.
The whole point of the gold standard is to make the code easy to use, and easy to understand should be part of that as well. If someone can't understand the code well enough to test it for gold standard candidate status, then there's something wrong with the code.
Often times, when I worked in support, it was necessary to support code that was written by those who had left the company. Those people were not available to ask why this or that was done. Therefore, if others cannot understand the code that is written, then the code either needs reworked, or it needs further documentation. I understand that often times, a special trick is used to make something happen that may not be the standard way of doing things. If there are comments explaining this nonstandard method, then all is well and good, otherwise, it's just making the code harder to understand, which is exactly the opposite of what the gold standard is trying to enforce.
The more eyeballs on the code as it's going through the gold process, the better. That's why there should be diffferent people do each level of processing, and no person may work on multiple levels that have similar requirements. I.E. if person A did the formatting, then Person B should be required to verify formatting, Person A cannot do this.
This maintains the standards, and ensures that no one person has too much influence on whether or not a given piece of code gets promoted to the next level(s).
It sounds like a lot of work, and it is, but the end result is well worth all the effort that goes into the process. Not to mention, that after everyone gets used to the process, things will move along nicely, and library objects will be added at a decent rate (assuming they pass cleanly through all the phases to get there).
Maybe I'm missing something here, but why add all the complexity and going into not invented here land.
Look no one is demanding software written to automotive, medical or aviation standards. Such stringency is overkill. Just reliable components that are documented. So a audience of commercial engineers and programmers can make a informed decision to buy the P2 or not. That's it, very simple.
If people have problems figuring out how to write good commented source code go read Code Complete.
Now here's a real world example:
Look at what Cypress did with their software defined controller line the PSOC1, 3 & 5 respectively. They put out a development system and included a set documented virtual peripherals and application notes:
This isn't beyond the scope of most coders here to create such a document.
As far as the Obex code goes, just leave it alone. The Gold Code project should only apply to C and PASM software components as this is what will sell the P2 to the commercial sector.
Lastly it's all up to Parallax, they'll have to drive the process if they want it to succeed. It's out of our hands.
Look no one is demanding software written to automotive, medical or aviation standards. Such stringency is overkill. Just reliable components that are documented.
You make incorrect assumptions here. Such stringency is the MINIMUM for reliable code. If you don't follow this we can go over it in detail. On the other hand, full FDA or FAA paperwork IS overkill. Don't confuse the two.
If people have problems figuring out how to write good commented source code go read Code Complete.
Very diplomatic of you. But ultimately this is a cop-out and and a poor excuse for not doing the "engineering" part of the task.
Lastly it's all up to Parallax, they'll have to drive the process if they want it to succeed. It's out of our hands.
And what process would this be? We haven't even reached an agreement on what the qualifiactions for a agold standard object would be, and what the gold standard is intended to specifically provide. "Gooder code" doesn't say anything.
If someone can't understand the code well enough to test it for gold standard candidate status, then there's something wrong with the code.
This is closer on point. It should be refined to say "some of a predetermined level of expertise." Only a handful of folks will ever understand FFT, a slightly larger group will understand VGA, the rest don't care.
We want to say " the folks that know about this code feel it does what its supposed to do".
to support code that was written by those who had left the company.
This is why we need adequate statement of requirements tests, and code functionality. This is my case for having requirements, tests, and code as minimum attributes for consideration to any gold standard.
The more eyeballs on the code as it's going through the gold process, the better.
This is why peer review must be part of the process. But for practical reasons, these reviewers must be comprised mostly of interested folks from the communitty, as Parallax staff could not handle the volume of review. It has to be self regulating by community interest, with minimal participation by parallax staff, otherwise it cannot happen.
This maintains the standards, and ensures that no one person has too much influence on whether or not a given piece of code gets promoted to the next level(s). It sounds like a lot of work, and it is, but the end result is well worth all the effort that goes into the process. Not to mention, that after everyone gets used to the process, things will move along nicely, and library objects will be added at a decent rate (assuming they pass cleanly through all the phases to get there).
The funny thing is that people that understand and appreciate proper process cannot get organized to create and maintain the process; and the folks that do not understand process seem to be actively working to prevent process. Even though any process would not cause anyone additional work, and all would enjoy the benefits.
The folks that understand process do it anyway because its a good idea, like brushing your teeth. It just a set of behaviors that make life easier, like keeping resistor of differnt values in separate containers. You don't have to do it, but folks that have to deal with a large number of resistors find it is useful. Folks that don't use process will never do it anyway, and that is fine. It just would be less likely that items from non-process folks would make it into the repository, which would be the same in any case.
The Gold Standard was an initiative to attract corporate customers to the Parallax Semiconductor Inc Propeller(s). Offering them ready made, reliable, Parallax branded and backed IP blocks for peripheral devices and other functionality the customers will be missing when looking at the Prop and comparing to the mass of other devices on the market
It is wasted time learning PAL when NTSC is the standard in the market where I live. C is the current standard. Reducing parts count, eliminating interupts and the ability to program in C will help. IMO the P1 and P2 specialists must create products that seize a competitive advantage. I don't think the horse-shoe industry welcomed the changes brought by the horseless carriage.
Not sure I get the drift of your post lardom. I have said a few times that Parallax Semiconductor needs to provide "soft peripherals" and other functionality written in C and/or assembler. I don't believe that target market for Parallax Semiconductor is going to give Spin the time of day. Clearly others think so too hence the push for GCC for the Propeller. Presenting that functionality as Spin objects, gold or otherwise, is a waste of time.
@Heater, I believe I agree with you. C programmers will remain C programmers. I learned to program a parallel processor using Parallax languages. It's a bit late for me to change. I think we will gain market share only if the Propeller offers tangible competitive advantages. There have to be consistent advantages that cause the developers of other chips to lose ground. Gaining market share is as much the responsibility of its programmers as it is of Parallax.
I tried to make the argument that the car was a technological improvement over the horse but horse-shoe makers strongly resisted the change.
I just get the impression that engineers scouring around for some device to fulfill some objective might come across the Propeller, start scanning the available info and simply dismiss it out of hand. What's a "COG"?, What is HUB? What, can only run 512 instructions of native code at full speed? What, no peripherals I need? What, I have to work in yet another language, Spin, which seems to offer no advantages over what I'm used to and has many disadvantages. OK next...
I have that impression because it happened to me. The first time a heard of a Propeller was in a catalog from the ELFA distributor. In that short summary I saw nothing I needed. It was a long while before my curiosity drew me back to it.
@Heater, perhaps you can explain why C programmers are drawn to the Propeller? (I have to add that had I known how much I like this stuff I would have majored in computer science 'waay' back in the days of Pascal, Fortran, Cobol... Yeah, I've been around for a while.)
It's not clear to me that C programmers are drawn to the Propeller. The Prop I is not a very good C engine what with having to use LMM which is a quarter the full speed and eats HUB space quickly or use CMM which is slower still, or be confined to COG sized code for full speed.
ImageCraft had no luck marketing their C compiler.
Still, I could be wrong, I have no idea how many Catalina and propgcc users are out there. Although we don't seem to be run over with C based Propeller projects.
The Prop II will be a much better proposition for C.
I think You are correct -- But that programs we will not see as share programs
---- Most of them are company ones and You know them not share theirs work.
It's not clear to me that C programmers are drawn to the Propeller. The Prop I is not a very good C engine what with having to use LMM which is a quarter the full speed and eats HUB space quickly or use CMM which is slower still, or be confined to COG sized code for full speed.
ImageCraft had no luck marketing their C compiler.
Still, I could be wrong, I have no idea how many Catalina and propgcc users are out there. Although we don't seem to be run over with C based Propeller projects. The Prop II will be a much better proposition for C.
Sorry, but I believe the "goldification" needs to be done by the original author. Who but that one person understands the code well enough to perform such a task? IMO, it would be an imposition to relegate that job to others. That being the case, the onus should be on Parallax to make that process as painless as possible. (But I won't comment further, since I still have a dog in that part of the show. )
-Phil
Sorry to jump into such a discussion...
But I agree with Phil here. The change of an object from its current form to a "Gold Standard" should be done by the original author, otherwise the object would be "updated" in its core functionality by someone that believes that he/she has a better idea how to make a certain method work or improve on it.
Any supposed "Gold Standard" should be written down as guidelines, and any person who would like their object stamped with the "Gold Standard" would need to have it follow those guidelines. There should be a group of people that should check any submitted "gold standard proposed" object and either accept or reject it on those criteria. Maybe provide pointers of where it needs to be fixed in order for it to be classed as a "Gold Standard" object.
I personally try to document my objects fully since if I come back to it six months later I won't remember what I had done, but I fall down in the terms of showing the connection of the hardware to the Prop (etc) in the documentation. But that is something I have listed to do in the future when I find the time... (and I keep looking for time but it seems to slip through my fingers...)
I think we all know that, and agree, basically.
All some of us are trying to do is help Ken get this kicked off.
The expectation/hope is that some of the experts here might be able to review some of their object^h^h^h, err IP blocks, and do a bit more testing, a little polish, and submit them as candidates for GSL.
I get the impression that you're of the mind that nothing should be done by anyone except Parallax. Which I think is a true waste of existing time spent by many here on rather good code that could put a nice foundation for much of what Parallax needs to do.
Parallax is ultimately responsible for making this happen, if you're not interested in helping then you're not. Others seen to be very interested, just look at the incredible amount of time and effort going into the P2 documentation project.
This is truely one of the best uC forums I'm happy to have found.
Maybe add a "Nominate for Gold" button in the existing OBEX. If an object gets enough nominations, the author has 1st shot at "goldifying" it, otherwise it's open for other contributors to modify and submit.
?
Jonathan
Now this is an excellent idea in my opinion. Simple, effective, community driven. If the object is useful, well written, well documented, stable and works correctly it will will naturally be promoted.
I'm puzzled as to why folks here think that during the process of making an object gold it is going to get rewritten. Nowhere in the steps I listed is there any kind of rewriting step.
The code is already there, the only thing the gold process does is all the cosmetic things that didn't get done during the initial creation process. If there is any rewriting, it's going to be the absolute minimum. Peer review and document checking/adding has nothing whatsoever to do with the original code. If it turns out that for some reason, the current coding bars it from the gold process for what ever reason, then at that point, it gets sent back to the original coder (assuming that person is available) to do any required rewriting, this is a review process, not a rewrite process. If the code falls somewhere during the process, then it is rejected, and can be resubmitted for gold library inclusion once the problems have been fixed.
I'll take the steps, drop them in a separate message by themselves, and we can discuss what needs done to flesh out the details, then we can work on getting those steps formalized by parallax, and after that, we can work on the next steps. It can't be done all at once, and it'd be silly to expect so. Let's get the details worked out first, then we'll see what (if anything) parallax wants to do with it all.
Either way, having the process identified and laid out will assist everyone, so it's not time wasted as some might think.
Having a set of high quality "soft peripherals" and other functions available with industry standard documentation is of course a great idea.
However in all the suggestions I read here about how to get that I see an awful lot of the word "should" as in "this should be done" and "someone should" or the "community should". Well who exactly? Most people are quite busy enough getting on with their lives anyway, if they are lucky they have time for their hobbies. When they do most would rather be working on getting their latest and greatest creation off the ground than slogging through perfecting the formatting and documentation of existing stuff. Not to mention doing good test coverage or adapting API's to whatever standards. That's how it works. Without enthusiasm nothing happens and enthusiasm for old and done stuff soon fades when you have the next shiny new idea in mind.
At the end of the day I believe it is down to Parallax. We are all eager customers some of whose efforts help move Parallax and the Propeller forward, by donating to OBEX for example, but at the end of the day we are not a free work force.
I'm puzzled as to why folks here think that during the process of making an object gold it is going to get rewritten
I must have missed the rewrite recommendations...
Good reusable code is well tested. Better reusable code is well tested and documented. Goldification goes one step further where Parallax supports the code base.
Whatever happened to the "Gold Standard"? Nothing... we all strive to write good code and some do better than others. The Gold Stamp is up to Parallax and business needs.
While I think this documentation is helpful, I don't think it goes far enough to be the only documentation for the object.
This is similar to the documentation we have seen from MS for .Net since they copied the JavaDoc style when they pretty much ripped off Java to create .Net (All of my clients are MS shops, so I say that lovingly)
The issue is the docs pretty much read like a programmers comments and tend to define things in terms of words that where already used. My tech writer hates this, very much.
For example we end up with a "DisplayValue" method and the docs say "Displays a Value"...
So anyway I think we need documentation beyond what is created automatically using the Automatic Spin Program Documenter.
So anyway I think we need documentation beyond what is created automatically using the Automatic Spin Program Documenter.
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.
Comments
Look how Cypress handles it's virtual peripheral library for the PSOC5. It's simple and straight forward. Each one is documented like a real world device. All Parallax has to do is come up up with say a dozen reference peripherals, document them and create a dozen projects ranging from industrial to medical that utilize them.
But all this has to be driven by Parallax, not some group of enthusiasts. The software has to be endorsed and supported by Parallax.
Yes, exactly and well put.
1. There are good arguments both ways about soft vs. hard peripherals. But having chosen the soft-peripheral approach, the Prop is really at a disadvantage if it doesn't have standard soft peripherals which (as much as possible) work as well/easily as MCU hard peripherals.
2. The OBEX is fine and so is improving it. But it doesn't really replace the need for Gold Standard #1. Process and standards are important, but the real issue is control, ownership and ultimate responsibility.
So rod1963 I really agree with... ...not to say there's no role for enthusiasts as 'cost-effective high-quality sub-contractors'.
...but as for... .
...I agree, but would just say it isn't as easy ($$$) as it sounds. Truly full 'Test', 'Verification', 'Characterization', 'Documentation', 'Support' is a lot of work, even for something simple like an I2C or UART. Big IC companies can afford it, but non-trivial for Parallax.
Seems really hard to proceed with Gold Standard unless/until Parallax has some $$$ to own it - and they've got a lot on their plate with P2, GCC, etc.
:frown:
Parallax owns it
Parallax drives it
standard soft peripherals documented like hard peripherals in application notes
oh, bother!
Coming up with reference designs is what companies are supposed to do if they want to market a new micro controller to the commercial sector. They are in a way a sales pitch to engineering professionals, I can easily think of a dozen projects to demonstrate and teach people about the Prop and so can anyone here. Some here are really good at it.
If Parallax can't afford that, then they shouldn't play in the commercial field at all.
Nor is there nothing that stops Parallax from asking some of the Prop experts here for their input for such reference designs. I'm sure most of them would be happy to contribute ideas and software.
And in terms of software. It just means well documented and tested virtual peripherals in C/PASM and not that many, just a dozen or so. Nothing fancy, just a set of drivers like IC2, SPI, Video, maybe a couple of digital filters, a PID loop, etc. For Parallax, they just have to make sure their Gold standard set of virtual peripherals work reliably and be well documented so others can make a informed decision about whether or not to use the Prop.
That's it.
Classic! Today, I have smiled.
A conventional recommendation might be Parallax raise some cash to fund it - but they aren't conventional which is why everyone here loves them.
Ok, I'm just being silly, because I am terrible at documentation. Writing code is what I like to do, but writing clean, formatted, well documented code? That's a whole different issue. I suspect others are the same.
What's needed is an approach that incorporates several of the suggestions in this thread. Feel free to amend/suggest where necessary.
1. code gets submitted to the obex.
(this already happens.
2. Code is used by others.
(this already happens.
3. If someone likes the code, they click the button to add a vote for gold standard library inclusion.
4. After x number of promotion clicks
(preferrably by folks who have been members for more than 30 days or so), then it gets raised as a flag for someone to look at.
5. The group of folks who look at the code are wide and varied, and as long as some percentage of those folks (say 25%) think it's good enough, the code then gets promoted again to some other status (pending gold standard maybe?)
6. A group of folks are selected to perform the goldification process, which would include documentation, formatting, whatever else is necessary)
7. code is checked by others (not any of those who already participated in previous rounds) again to verify it meets whatever requirements there may be for final acceptance.
8. if all conditions are met, then code is inducted into the gold standard library, and there is much rejoycing.
Obviously, there's plenty of fleshing out necessary in this process, but much of this work can be done automatically, and some of it can be done by folks who aren't experts on the objects, because experts on software aren't necessary to verify formatting just for example.
Obviously, the higher up the chain the code goes, the less folks there will be with the required skills to pass it through the process, but hopefully, this won't matter, because objects will be filtering through at all levels at any given time, so there will be no lack of work for those who want it.
There should probably be a preliminary step 0 to identify if this code should be included into the gold library at all, for example, nobody needs hello world code in a gold standards library, but that's not to say simple things shouldn't or couldn't be included, some kind of determination would have to be made before it gets voted through step 1.
Coding for buttons to automate most of the process (nominating for gold standard library status, checking formatting, and so on) would be easy to write since php is the language of choice these days for projects like this, and I'm sure there's several forum members besides myself who have experience in php coding, so it would certainly be possible to make the process as streamlined as it can, but still leave room for improvement if process seems to break down during any given stage.
There's an example of this sort of thing that takes place on distributed proofreaders. Books are scanned into the computer (this is for public domain books) The book then goes through as many as 6 levels of proofing/formatting/checking (but never less than 3) before it's deemed complete, and is sent off to project gutenberg for inclusion in their catalog.
It's a process that works well, and has been working well for many years.
I see no reason why something similar couldn't be put in place here to make obex objects into gold standard library objects.
When I worked at CSC, they followed the cmm standard, code wasn't allowed into the production system until it had undergone several levels of peer review, checklist passing, document writing, testing and all kinds of things before it was allowed to be imported into the production system. At times, it was an extremely frustrating process, but as a result, after this process was implemented, production system errors dropped to a very small percentage of what they had been before the system was put in place.
So, in short, I'm simply saying it's certainly possible, many think it's necessary, and I see no reason not to do it.
It will be work for sure, but in the end, we'll all benefit from it, and as a result, there will be greater selection for those hunting for code to help with particular tasks.
It may be a big job, but I'm perfectly willing to take up as much slack as I can to make this happen, and that includes building php database interfaces, making mysql databases, helping write the documents that get used during the process, and maybe even participate in the process when it's all done and tested to completion. As I pointed out above, documentation and pretty code isn't my forte, but enough people believe this is necessary, and I like parallax enough that I'm willing to step up and do what I can to make it happen, so feel free to let me know what I've missed here. There's enough of us that the process shouldn't be a major burden on anyone, though it will take time. I think it can be done though, so whoever wants to help, let me know what parts need changed, and I'll update the steps above accordingly. This should at least get the ball rolling, after that, we can work with what comes next.
-Phil
Phil. While I understand where you're coming from, in this case, I strongly disagree.
The whole point of the gold standard is to make the code easy to use, and easy to understand should be part of that as well. If someone can't understand the code well enough to test it for gold standard candidate status, then there's something wrong with the code.
Often times, when I worked in support, it was necessary to support code that was written by those who had left the company. Those people were not available to ask why this or that was done. Therefore, if others cannot understand the code that is written, then the code either needs reworked, or it needs further documentation. I understand that often times, a special trick is used to make something happen that may not be the standard way of doing things. If there are comments explaining this nonstandard method, then all is well and good, otherwise, it's just making the code harder to understand, which is exactly the opposite of what the gold standard is trying to enforce.
The more eyeballs on the code as it's going through the gold process, the better. That's why there should be diffferent people do each level of processing, and no person may work on multiple levels that have similar requirements. I.E. if person A did the formatting, then Person B should be required to verify formatting, Person A cannot do this.
This maintains the standards, and ensures that no one person has too much influence on whether or not a given piece of code gets promoted to the next level(s).
It sounds like a lot of work, and it is, but the end result is well worth all the effort that goes into the process. Not to mention, that after everyone gets used to the process, things will move along nicely, and library objects will be added at a decent rate (assuming they pass cleanly through all the phases to get there).
Look no one is demanding software written to automotive, medical or aviation standards. Such stringency is overkill. Just reliable components that are documented. So a audience of commercial engineers and programmers can make a informed decision to buy the P2 or not. That's it, very simple.
If people have problems figuring out how to write good commented source code go read Code Complete.
Now here's a real world example:
Look at what Cypress did with their software defined controller line the PSOC1, 3 & 5 respectively. They put out a development system and included a set documented virtual peripherals and application notes:
Here's one of their application notes:
http://www.cypress.com/?docID=41321
Here's a example of one documented virtual peripheral.
http://www.cypress.com/?docID=39397
This isn't beyond the scope of most coders here to create such a document.
As far as the Obex code goes, just leave it alone. The Gold Code project should only apply to C and PASM software components as this is what will sell the P2 to the commercial sector.
Lastly it's all up to Parallax, they'll have to drive the process if they want it to succeed. It's out of our hands.
You make incorrect assumptions here. Such stringency is the MINIMUM for reliable code. If you don't follow this we can go over it in detail. On the other hand, full FDA or FAA paperwork IS overkill. Don't confuse the two.
Very diplomatic of you. But ultimately this is a cop-out and and a poor excuse for not doing the "engineering" part of the task.
And what process would this be? We haven't even reached an agreement on what the qualifiactions for a agold standard object would be, and what the gold standard is intended to specifically provide. "Gooder code" doesn't say anything.
This is closer on point. It should be refined to say "some of a predetermined level of expertise." Only a handful of folks will ever understand FFT, a slightly larger group will understand VGA, the rest don't care.
We want to say " the folks that know about this code feel it does what its supposed to do".
This is why we need adequate statement of requirements tests, and code functionality. This is my case for having requirements, tests, and code as minimum attributes for consideration to any gold standard.
This is why peer review must be part of the process. But for practical reasons, these reviewers must be comprised mostly of interested folks from the communitty, as Parallax staff could not handle the volume of review. It has to be self regulating by community interest, with minimal participation by parallax staff, otherwise it cannot happen.
This.
The folks that understand process do it anyway because its a good idea, like brushing your teeth. It just a set of behaviors that make life easier, like keeping resistor of differnt values in separate containers. You don't have to do it, but folks that have to deal with a large number of resistors find it is useful. Folks that don't use process will never do it anyway, and that is fine. It just would be less likely that items from non-process folks would make it into the repository, which would be the same in any case.
IMO the P1 and P2 specialists must create products that seize a competitive advantage. I don't think the horse-shoe industry welcomed the changes brought by the horseless carriage.
I tried to make the argument that the car was a technological improvement over the horse but horse-shoe makers strongly resisted the change.
I have that impression because it happened to me. The first time a heard of a Propeller was in a catalog from the ELFA distributor. In that short summary I saw nothing I needed. It was a long while before my curiosity drew me back to it.
The Prop I is not a very good C engine what with having to use LMM which is a quarter the full speed and eats HUB space quickly or use CMM which is slower still, or be confined to COG sized code for full speed.
ImageCraft had no luck marketing their C compiler.
Still, I could be wrong, I have no idea how many Catalina and propgcc users are out there. Although we don't seem to be run over with C based Propeller projects.
The Prop II will be a much better proposition for C.
I think You are correct -- But that programs we will not see as share programs
---- Most of them are company ones and You know them not share theirs work.
OK hera a example. This is done with Phil's wonderful Spin Documenter.
so it gets generated out o the existing comments in the source of the spin File
Here a link to the spin-File - File is attached below ...
The process is simple.
Obey some rules Phil declared while documenting your spin-source-file
Open your browser on this url http://www.phipi.com/spin2html/
Upload your spin-file and save the resulting html-page
done.
For a more complex example you can look at the the documentation for some upcoming product...
Here I added some simple pages to build a menu-system around the pages generated whith Phil's Spin Documenter.
BTW this is not really new. The original Forum-post containing Phil's rules...
Enjoy!
Mike
Sorry to jump into such a discussion...
But I agree with Phil here. The change of an object from its current form to a "Gold Standard" should be done by the original author, otherwise the object would be "updated" in its core functionality by someone that believes that he/she has a better idea how to make a certain method work or improve on it.
Any supposed "Gold Standard" should be written down as guidelines, and any person who would like their object stamped with the "Gold Standard" would need to have it follow those guidelines. There should be a group of people that should check any submitted "gold standard proposed" object and either accept or reject it on those criteria. Maybe provide pointers of where it needs to be fixed in order for it to be classed as a "Gold Standard" object.
I personally try to document my objects fully since if I come back to it six months later I won't remember what I had done, but I fall down in the terms of showing the connection of the hardware to the Prop (etc) in the documentation. But that is something I have listed to do in the future when I find the time... (and I keep looking for time but it seems to slip through my fingers...)
I think we all know that, and agree, basically.
All some of us are trying to do is help Ken get this kicked off.
The expectation/hope is that some of the experts here might be able to review some of their object^h^h^h, err IP blocks, and do a bit more testing, a little polish, and submit them as candidates for GSL.
I get the impression that you're of the mind that nothing should be done by anyone except Parallax. Which I think is a true waste of existing time spent by many here on rather good code that could put a nice foundation for much of what Parallax needs to do.
Parallax is ultimately responsible for making this happen, if you're not interested in helping then you're not. Others seen to be very interested, just look at the incredible amount of time and effort going into the P2 documentation project.
This is truely one of the best uC forums I'm happy to have found.
Now this is an excellent idea in my opinion. Simple, effective, community driven. If the object is useful, well written, well documented, stable and works correctly it will will naturally be promoted.
The code is already there, the only thing the gold process does is all the cosmetic things that didn't get done during the initial creation process. If there is any rewriting, it's going to be the absolute minimum. Peer review and document checking/adding has nothing whatsoever to do with the original code. If it turns out that for some reason, the current coding bars it from the gold process for what ever reason, then at that point, it gets sent back to the original coder (assuming that person is available) to do any required rewriting, this is a review process, not a rewrite process. If the code falls somewhere during the process, then it is rejected, and can be resubmitted for gold library inclusion once the problems have been fixed.
I'll take the steps, drop them in a separate message by themselves, and we can discuss what needs done to flesh out the details, then we can work on getting those steps formalized by parallax, and after that, we can work on the next steps. It can't be done all at once, and it'd be silly to expect so. Let's get the details worked out first, then we'll see what (if anything) parallax wants to do with it all.
Either way, having the process identified and laid out will assist everyone, so it's not time wasted as some might think.
However in all the suggestions I read here about how to get that I see an awful lot of the word "should" as in "this should be done" and "someone should" or the "community should". Well who exactly? Most people are quite busy enough getting on with their lives anyway, if they are lucky they have time for their hobbies. When they do most would rather be working on getting their latest and greatest creation off the ground than slogging through perfecting the formatting and documentation of existing stuff. Not to mention doing good test coverage or adapting API's to whatever standards. That's how it works. Without enthusiasm nothing happens and enthusiasm for old and done stuff soon fades when you have the next shiny new idea in mind.
At the end of the day I believe it is down to Parallax. We are all eager customers some of whose efforts help move Parallax and the Propeller forward, by donating to OBEX for example, but at the end of the day we are not a free work force.
Good reusable code is well tested. Better reusable code is well tested and documented. Goldification goes one step further where Parallax supports the code base.
Whatever happened to the "Gold Standard"? Nothing... we all strive to write good code and some do better than others. The Gold Stamp is up to Parallax and business needs.
While I think this documentation is helpful, I don't think it goes far enough to be the only documentation for the object.
This is similar to the documentation we have seen from MS for .Net since they copied the JavaDoc style when they pretty much ripped off Java to create .Net (All of my clients are MS shops, so I say that lovingly)
The issue is the docs pretty much read like a programmers comments and tend to define things in terms of words that where already used. My tech writer hates this, very much.
For example we end up with a "DisplayValue" method and the docs say "Displays a Value"...
So anyway I think we need documentation beyond what is created automatically using the Automatic Spin Program Documenter.
C.W.
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