That's good on paper and not practical. Unless, 1) We're launching a rover to Mars. 2) Parallax ask for a library/driver with very specific INs and OUTs. Most of us are writing this stuff in our spare time with spousal permission of course. When the opportunity shows itself and I have the time to sit and code, I'll do as pedward outlined (which is TDD). I don't see myself writing specs for myself. That's goofy...
This is not true. OK, maybe its goofy to do it right, but you can do what ever you want. The "not practical" part is nonsense. If we can't tell what the code is intended to do, and whether of not it does, then the code is useless.
If three steps is too much, then don't do them. Do what ever you want. The process only aims to measure to what extent these three things are present and complete.
In case where all three are complete, we can measure this and evaluate whether it was effective in obtaining reliable code. In case there all three are not complete, we can ALSO evaluate the extent to which we get reliable code. And we adjust the process to the point where we establish the absolute minimum required to reasonably expect to get what we want.
Braino, I think what you're talking about can be done in parallel with some of the beginnings of writing code, but does need to be complete before the code can be considered complete. So, would you like to try writing the documentation, and maybe tests, for the serial driver I posted?
I think the process for process' sake approach will not lead to a useful conclusion. I favor productivity over superfluous process. I can spend 15 minutes looking at code to yield a high level assessment on the quality and the potential outcome from a selection of code.
I completely agree.
Saying that a face value statement "Here is support for chip X" is invalid without process documentation is a ridiculous assertion.
Here is where you misunderstand. Don't make it so hard. This is easy. Here, when you say "process documentation", you are automatically assuming something that is huge and burdensome. If that's ever the case, you are probably doing it wrong.
Debugging of code is NEVER approached from "read some document the author wrote" because if the author wrote buggy code, the document is probably buggy too.
Debugging of code is suppose to be completed before the code ever gets reviewed. WE ARE NOT DEBUGGING CODE at this point. The software developer did that in private as part of development. This process is intended to be well past the debugging stage. This is very important distinction, and likely the source of your misunderstanding.
When trying to work with someone else's code, you instrument and test incrementally to your own satisfaction, that's the fast path.
The point of Gold Standard is to have code that we DON'T need to instrument and test incrementally. We want to able to show that the instrumentation and testing has already been done, and here is the result that shows it. At this point, we can say, this looks Golden for these reasons, we have confidence that it will behave as expected, according to these parameters.
Don't confuse investigation, development, and final review. When these are jumbled together, we get a poor result. This process is final review, and looks for some indication that the investigation and development has been completed.
Braino, I think what you're talking about can be done in parallel with some of the beginnings of writing code, but does need to be complete before the code can be considered complete.
Yes. The first bits of code are investigation. The code that has all the tests and references is the final code. The references and tests determine the final code. The ERROR is when one tires to use the investigation code to determine the references and tests.
[/QUOTE]So, would you like to try writing the documentation, and maybe tests, for the serial driver I posted?[/QUOTE]
This is a good question. I can review what you wrote. But I can NOT write the documentation for you, only you can. Only you know what you used as reference, and you know what you did. I mean, of course I could try, and it would involve asking you what references you used, and what you did. Either way, you need to spend the effort getting the stuff out of your head and into mine. Which, of course, is the documentation we are looking for in the first place.
So here's how this works the easiest. I ask, you answer. Actually, the reviewers ask, and the team answers. The answers make of the documentation, and somebody organizes it, and that's our docs. I might be able to lead the asking, and organizing, but very quickly we begin to catch on, and it is very much more efficient (and quicker) for the author to do the "author steps". First time around, I'll do all the work, if you work with me.
So here's the first question (I'm specifically asking this without first looking, for the benefit of those following along):
Where in your code is that statement of what the code is intended to perform?
I can review what you wrote. But I can NOT write the documentation for you, only you can.
I have a really hard time starting documents. If you take a few guesses about what I've done, and start writing one, I can correct it and expand on it, but I just can't start. (Part of a learning disability). I am, however, pretty good at emulation, so once I have an example to start from, I can usually make my own reasonably well.
So here's how this works the easiest. I ask, you answer. Actually, the reviewers ask, and the team answers. The answers make of the documentation, and somebody organizes it, and that's our docs. I might be able to lead the asking, and organizing, but very quickly we begin to catch on, and it is very much more efficient (and quicker) for the author to do the "author steps". First time around, I'll do all the work, if you work with me.
So here's the first question (I'm specifically asking this without first looking, for the benefit of those following along):
Where in your code is that statement of what the code is intended to perform?
Well, I was going to say "In the header file", but I just realized there isn't an overall description there; only function header comments. There's a small description in the commit message, but it should probably be put into its own document somewhere. I'll try to add that soon.
In the mean time, can you go through and comment on the function-header-comments? That will probably give me a good starting point to document them better.
This is not true. OK, maybe its goofy to do it right, but you can do what ever you want. The "not practical" part is nonsense. If we can't tell what the code is intended to do, and whether of not it does, then the code is useless.
If three steps is too much, then don't do them. Do what ever you want. The process only aims to measure to what extent these three things are present and complete.
I agree there has to be an understanding of function. prof_braino, you're spinning this stuff and it's hilarious. I never once said no code descriptions.
I can understand where you're coming from, jazzed, though my own tolerance may be much higher due to my own difficulty in communicating, in general. I'm hoping that Braino and I can produce an example of what he's talking about, as I suspect the words he's using make the process seem far more complex than it really is, but I still don't fully understand what he means. That's why I requested an example.
Have you actually read it? I re-wrote the C parts, from scratch, based on the SPIN part, and used a diff program to merge the original assembly code with the boilerplate produced by spin2cpp. There should be very little junk left.
Let's just please work through an example of what prof_braino is suggesting. Either with circuitsoft's code or the original full duplex serial.
It may work out that once we see an example more people will be happy with it, or maybe it will point out all the serious flaws in it and how it will bring life as we know it to a grinding halt.
Would it make sense to add a file called ffds1.README, or would ffds1.txt make more sense?
You already have ffds1.c, and ffds.h, and fdds1m.s; could you simply add a sentence to one of these? Keep it simple until we have a compelling reason to make a separate file.
For example, "High level requirement: This implements general serial support." or similar, whatever says it best.
The next thing to have is a list of references.
For any prop software, the first reference would be the prop manual. Yes, this is obvious, but we want to list it, and not say "its assumed". I guess we're using prop manual version 1.1, this should be the first item in the reference list.
For circuitsoft's serial function, we want to know where serial function is defined. Is there a simple reference that tells us what all the functions we need and how they are supposed to work?
The next thing to have is a list of references.
For any prop software, the first reference would be the prop manual. Yes, this is obvious, but we want to list it, and not say "its assumed". I guess we're using prop manual version 1.1, this should be the first item in the reference list.
OK, I think I'll put these in the .h file, as that is the one I most expect people to read as documentation.
For circuitsoft's serial function, we want to know where serial function is defined. Is there a simple reference that tells us what all the functions we need and how they are supposed to work?
I don't know if there's a list of functions required for a serial driver. There is a comment on each function in the header file that describes what that function does and how to use it.
...For circuitsoft's serial function, we want to know where serial function is defined. Is there a simple reference that tells us what all the functions we need and how they are supposed to work?
As mentioned all that is in the header file. However, since there are no "agreed upon requirements" for C, SPIN, or any other language, we have no idea if it is done right or if the content is sufficient.
Still waiting for that requirements list from you. You should define all the requirements that you expect to meet since you assert that 90% is incomplete (you have not done enough work). This is the project lead's job. You are the lead right?
It's very simple you know. Make a list in excel, give each item a bullet number, a brief description, a link to detailed description of the requirement, and a link to approvals. Everyone collaborates. Then once everything is finalized (approved by participants), you can make a check list for each project which can be used in reviews.
OK, I think I'll put these in the .h file, as that is the one I most expect people to read as documentation.
This is good.
I don't know if there's a list of functions required for a serial driver. There is a comment on each function in the header file that describes what that function does and how to use it.
The comment in the header file describing each function is needed, but it is a separate issue.
What I am asking about here, how do you know what a serial function is supposed to do? That is, where did you get all those functions? How do you know what a stop bit is supposed to look like? How do we figure out what the half bit period is? They have to come from someplace, so where would a novice look to understand this serial function? For example, can we just link to a wiki article like:
As mentioned all that is in the header file. However, since there are no "agreed upon requirements" for C, SPIN, or any other language, we have no idea if it is done right or if the content is sufficient.
Still waiting for that requirements list from you. You should define all the requirements that you expect to meet since you assert that 90% is incomplete (you have not done enough work). This is the project lead's job. You are the lead right?
It's very simple you know. Make a list in excel, give each item a bullet number, a brief description, a link to detailed description of the requirement, and a link to approvals. Everyone collaborates. Then once everything is finalized (approved by participants), you can make a check list for each project which can be used in reviews.
1. No, it is not in the header file. But the author has agreed to put it there. No offense, but you are not getting it yet.
2. No, the requirements are as stated above several times: A) what does it do? how do we know it does it? C) Did you check it? D) Can anybody aggree you did this?
3. No, I am NOT project lead. Circuit soft is project lead, its his project. I am SQE; I just ask "Did you do any of this process? (as described in step 2)"; and then I report whether or not I got an answer.
4. You can do stuff in excel if you want, if you feel it makes life easier. I have no restrictions on the actual mechanics of how folks do their work, I just need an indication that it was done. I advise that you don't make it harder than it needs to be.
Let's just please work through an example of what prof_braino is suggesting. Either with circuitsoft's code or the original full duplex serial.
It may work out that once we see an example more people will be happy with it, or maybe it will point out all the serious flaws in it and how it will bring life as we know it to a grinding halt..
This would be the recommended we to go.
The idea is that we start anywhere with a line in the sand. Then we adjust the process to meet our needs.
I think circuitsoft's serial will be just fine, we just want to work through the process on some example at this point, it's his effort, we can use his code. We can also use any other code at the same time, as the process it intended to handle multiple items in parallel. And it is, we had suggests for more items, those just haven't made it any further yet.
Concerning jazzed' comment from #101: the assessment of suitability of a given piece of software based on its point of origin is incorrect. By design, the process should be able to evaluate any software from any source. Any deficiencies in the software are identified along the way. Reaching the "end" of the process means we've either corrected all the deficiencies, or stopped working on it. Even then, more deficiencies can be found and corrected.
In any case we should continue and see how far we get.
1
2. No, the requirements are as stated above several times: A) what does it do? how do we know it does it? C) Did you check it? D) Can anybody aggree you did this?
3. No, I am NOT project lead. Circuit soft is project lead, its his project. I am SQE; I just ask "Did you do any of this process? (as described in step 2)"; and then I report whether or not I got an answer.
PB, not to minimize your job but if this is what your job consists of, then I want your job!!
This is a very simple wrapper around a complex issue. I'm jaded as to "process" because of my employer but I think I understand the underlying basics of quality and specifying a "Gold Standard" although I'm seeing different priorities and needs for the "Gold Standard Process"
Jazzed is correct in that the Spin and PropGCC items need to be separated. The Gold Standard Process linked to earlier does a great job of specifying a coding standard for Spin objects. This doesn't exist for PropGCC and needs to be developed so everyone is coding from the same page. So, except for your 4 questions, 90% of the PropGCC work needs to be done. There is a tremendous amount of coding style and interface standards to agree upon for a PropGCC standard.
I think your questions answer the what is it supposed to do and does it do it questions of a standard piece of code, but those seem rather obvious and trivial. If it didn't do what it didn't do what it was purported to do, then it has no reason to be discussed as a gold standard. Basic functionality is assumed - if I put X into the black box and expect to get Y out the other side, then I better get Y. If you call it an I2C driver and it doesn't talk I2C, then there's a basic problem.
The more important question is the HOW it does it and HOW you get X in and Y out. These are where the Gold Object Standards documents come in and your process doesn't ask or answer those questions. I won't or don't want to figure out a bunch of different API/Interfaces in order to hook things together. I really don;t want a kit that has slotted, phillips and torx fasteners just because three different people went to the store room to get parts and they each have their favorite. I want to use just one screw driver and if I can't, I won't be buying another kit from you.
So far, we have:
1) a standard document outlining coding conventions, API, documentation standards, etc.
2) a process to ask if all the boxes on the checklist are filled in and if others agree they should be filled in - questions asked and answered - this can really be handled by a conscientious coder and a knowledgeable reviewer or two.
A third component to the Gold Standard equally important to #1 above is what objects need to be in the standard set. The library that comes with the Propeller Tool has a mix of essential, nice to have and fun and interesting demos. The essentials need to be up to Gold Standard (I think there are also more "essentials"), the nice to have should be up to a gold standard as far as interfacing API if possible. The demos are fun and interesting but not really needed to be at Gold Standard. There should be a solid set of Gold Standard soft peripherals since that is one of the big selling points of the Propeller architecture. For example, if Microchip or Atmel have a chip with this tyope of peripheral, there should be a Gold Standard Propeller peripheral to match and an app note to show how to use it. Serial, I2C, SPI, RTC, PWM, etc. should have Gold Standard code with app notes. NES game control interfaces, microphone to headphone, Microsoft Joystick support, etc. aren't really Gold Standard items even though they may be interesting to a hobbyist. This is where there is a conflict with some community sourced tool libraries. Great fun and brilliant pieces of code for a hobbyist but maybe not so useful to an Engineer looking to use a Propeller in a new design.
Other than this little contribution, I'll stay out of the Gold Standard Process debate. If it's just 5 or 6 questions that need to be asked and documented during the code development process, I think I can handle that. (I've probably even asked and answered the questions over the years)
When we get to asking how best to come up with API's and support for the various memory models with consistent, standard code, then my ears will perk up again.
Carry on, all, whatever SQC process you come up with should be able to be wrapped around whatever functional requirements and standards are needed to develop solid Gold Standard Objects.
PB, not to minimize your job but if this is what your job consists of, then I want your job!!
No, you don't. We get paid in hatred, as evidenced by the easily recognizable mob with torches and pitchforks.
The stuff seems obvious and trivial, because it IS obvious when you think about it, and trivial to do NOW, but a huge problem if you don't think about it and it comes back to bite you. Get it squared away early and upfront.
Until we establish the basics of how we describe our highest level requirements, we are never going to get to describing how to go about testing them, and we will never get to looking at code that attempts to pass those tests.
As I may have said before, code standards are irrelevant UNTIL WE GET TO THE CODE. Yes jazzed is correct that spin and C should be handled with different coding standards. We are nowhere near the of discussion code. Leave that to the side till later. Right now I just want to establish out what the project plans to do and how to check if it does that.
If it didn't do what it didn't do what it was purported to do, then it has no reason to be discussed as a gold standard.
Bingo. So, the question remains, how do we determine what its supposed to do? If we don't know that, we can't determine if it does it or not. How do we check? Until these questions are answered, the rest is moot. This very basic early step is often skipped, and doing so is a main contributor to problems and failure.
Process guy braino advises it is not expedient to work on step three until we complete step one.
Bingo. So, the question remains, how do we determine what its supposed to do? If we don't know that, we can't determine if it does it or not. How do we check? Until these questions are answered, the rest is moot. This very basic early step is often skipped, and doing so is a main contributor to problems and failure.
Why are we messing with code the author submitter verified is not working?
Why are we messing with code the author submitter verified is not working?
I don't think "the process" is meant for submitters with malicious intent (although it may work there, too). Instead, I think the "how do we know it does what it's supposed to" is for mistakes such as not sending a stop bit when the transmitted byte ends with a 1, or something like that.
Why are we messing with code the author verified is not working?
We are not. This is the experiment. At this point, we are learning the process itself. At this point in the process, we want to define exactly what the project is expected to do, so we can test whether it does that.
By doing this step, the author (who is still in the investigation or development stage) will have the necessary information to make the code function. In fact, I would guess that the reason the code isn't functioning is because this step has not be completed (he can let us know after). In the very least, doing this step will make coding easier.
I don't think "the process" is meant for submitters with malicious intent (although it may work there, too). Instead, I think the "how do we know it does what it's supposed to" is for mistakes such as not sending a stop bit when the transmitted byte ends with a 1, or something like that.
No, I mean the actual source code to be goldified does not work.
Ok, I see the problem. As a SQE, you are competent in testing the end result. I accept that. Let the rest of us worry about the rest.
However, the requirements must be codified and ratified, otherwise it is a complete waste of time. Going through the exercise of reviewing code is a moving target without having a list of agreed to requirements.
1. No, it is not in the header file. But the author has agreed to put it there. No offense, but you are not getting it yet.
It was satisfactory to me when I looked. Obviously the requirements are misunderstood because they are not listed in a single place or agreed to otherwise we could both objectively say yes or no.
2. No, the requirements are as stated above several times: A) what does it do? how do we know it does it? C) Did you check it? D) Can anybody aggree you did this?
This is a high level list of requirements.
So, taking what you have listed and expanding on it. Anyone is welcome to comment.
A) what does it do?
- ok, so where is this described for spin, pasm, c, forth, basic, etc... ?
B) how do we know it does it?
- ok, you have mentioned test plan. do you have any guidelines for testing? is external equipment required? can just anyone run the test?
C) Did you check it?
- sure, i would rephrase it as what was your test process? what unit tests did you do? can your library be easily used in the context of other programs?
D) Can anybody agree you did this?
- external testers and code reviewers can follow the guidelines and verify
My additions:
E) Did the programmer describe the function interface in detail?
This is very important for code sharing so it is listed separately from standard compliance.
F) Are there problems with coding standard compliance (if any)?
Bullets for the coding standard must be placed somewhere obvious.
G) Take the generic bullet items from that other document and place them here.
H) Add links to specifics of each language.
And to end the list, the persons who ratified to the requirements should be documented.
0) Establish Gold Standard API and coding standards for languages in the Gold Standard libraries
0a) identify needed Gold Standard objects on Parallax's product roadmaps
1) does the code under submission perform a needed Gold Standard function (is there a better candidate out there?) (has the function already been added to the Gold Standard collection?) (is it something that shoudl be a Gold Standard item?)
2) Has it been written to Gold standard coding and API standards?
3) Does it have supporting documentation (internal documentation to code source PLUS an app note)
4) peer review and requirements checklist, mentoring, coaching, debating (lather, rinse, repeat)
5) update standards documents if needed (need to keep backward compatibility if at all possible)
6) Publish as Gold Standard with all documentation
7) identify next most needed object in Parallax's product roadmap
8) return to 1
I haven't seen it specifically stated as a step, but it seems part of the gold standard process is to throw rocks at the couple of people that are actually trying to put together an example of what they are talking about.
I think it's clear that the steps they are working on are not the entire process, but they are an important part of the process.
It looks like those steps fit the first part of the process outlined by Jazzed, so how about letting them complete them as an example.
It would be nice to see some action on the other parts mentioned by Jazzed, but who wants to step up and help when it just makes them a target for more rocks?
I'll offer to help with a task or two if Jazzed wants to setup a task list of some things we can do to help with an example of the parts of his list not covered by what prof_braino and circuitsoft are working on.
I've been following this thread for the past couple of weeks, and it doesn't seem to be any closer to a Gold Standard process than when it started. I really don't understand Prof_Braino's posts. They just seem to overcomplicate the issue. Is this thread trying to circumvent the process that is already in place on the parallaxsemiconductor.com site? It seems that the process that Parallax has already posted is fine. They've posted the requirements for a Gold Standard object, and a list of objects that they've like to see. Anybody can earn $50 credit for each Gold Standard object just by guilding an existing object that's on the list and submitting it to Parallax for approval. I don't understand the problem that's trying to be solved in this thread
Comments
This is not true. OK, maybe its goofy to do it right, but you can do what ever you want. The "not practical" part is nonsense. If we can't tell what the code is intended to do, and whether of not it does, then the code is useless.
If three steps is too much, then don't do them. Do what ever you want. The process only aims to measure to what extent these three things are present and complete.
In case where all three are complete, we can measure this and evaluate whether it was effective in obtaining reliable code. In case there all three are not complete, we can ALSO evaluate the extent to which we get reliable code. And we adjust the process to the point where we establish the absolute minimum required to reasonably expect to get what we want.
I completely agree.
Here is where you misunderstand. Don't make it so hard. This is easy. Here, when you say "process documentation", you are automatically assuming something that is huge and burdensome. If that's ever the case, you are probably doing it wrong.
Debugging of code is suppose to be completed before the code ever gets reviewed. WE ARE NOT DEBUGGING CODE at this point. The software developer did that in private as part of development. This process is intended to be well past the debugging stage. This is very important distinction, and likely the source of your misunderstanding.
The point of Gold Standard is to have code that we DON'T need to instrument and test incrementally. We want to able to show that the instrumentation and testing has already been done, and here is the result that shows it. At this point, we can say, this looks Golden for these reasons, we have confidence that it will behave as expected, according to these parameters.
Don't confuse investigation, development, and final review. When these are jumbled together, we get a poor result. This process is final review, and looks for some indication that the investigation and development has been completed.
Yes. The first bits of code are investigation. The code that has all the tests and references is the final code. The references and tests determine the final code. The ERROR is when one tires to use the investigation code to determine the references and tests.
[/QUOTE]So, would you like to try writing the documentation, and maybe tests, for the serial driver I posted?[/QUOTE]
This is a good question. I can review what you wrote. But I can NOT write the documentation for you, only you can. Only you know what you used as reference, and you know what you did. I mean, of course I could try, and it would involve asking you what references you used, and what you did. Either way, you need to spend the effort getting the stuff out of your head and into mine. Which, of course, is the documentation we are looking for in the first place.
So here's how this works the easiest. I ask, you answer. Actually, the reviewers ask, and the team answers. The answers make of the documentation, and somebody organizes it, and that's our docs. I might be able to lead the asking, and organizing, but very quickly we begin to catch on, and it is very much more efficient (and quicker) for the author to do the "author steps". First time around, I'll do all the work, if you work with me.
So here's the first question (I'm specifically asking this without first looking, for the benefit of those following along):
Where in your code is that statement of what the code is intended to perform?
Sounds good to me.
Well, I was going to say "In the header file", but I just realized there isn't an overall description there; only function header comments. There's a small description in the commit message, but it should probably be put into its own document somewhere. I'll try to add that soon.
In the mean time, can you go through and comment on the function-header-comments? That will probably give me a good starting point to document them better.
http://forums.parallax.com/showthread.php/144795-My-attempt-at-a-quot-Gold-Standard-quot-process?p=1155379&viewfull=1#post1155379
I agree there has to be an understanding of function. prof_braino, you're spinning this stuff and it's hilarious. I never once said no code descriptions.
That's exactly right. I'm not bound to your ramblings.
Trying to use the output of the spin2cpp program to create a "standard" module is not a good way to go. Please use another example.
I can understand where you're coming from, jazzed, though my own tolerance may be much higher due to my own difficulty in communicating, in general. I'm hoping that Braino and I can produce an example of what he's talking about, as I suspect the words he's using make the process seem far more complex than it really is, but I still don't fully understand what he means. That's why I requested an example.
It may work out that once we see an example more people will be happy with it, or maybe it will point out all the serious flaws in it and how it will bring life as we know it to a grinding halt.
C.W.
You already have ffds1.c, and ffds.h, and fdds1m.s; could you simply add a sentence to one of these? Keep it simple until we have a compelling reason to make a separate file.
For example, "High level requirement: This implements general serial support." or similar, whatever says it best.
For any prop software, the first reference would be the prop manual. Yes, this is obvious, but we want to list it, and not say "its assumed". I guess we're using prop manual version 1.1, this should be the first item in the reference list.
For circuitsoft's serial function, we want to know where serial function is defined. Is there a simple reference that tells us what all the functions we need and how they are supposed to work?
As mentioned all that is in the header file. However, since there are no "agreed upon requirements" for C, SPIN, or any other language, we have no idea if it is done right or if the content is sufficient.
Still waiting for that requirements list from you. You should define all the requirements that you expect to meet since you assert that 90% is incomplete (you have not done enough work). This is the project lead's job. You are the lead right?
It's very simple you know. Make a list in excel, give each item a bullet number, a brief description, a link to detailed description of the requirement, and a link to approvals. Everyone collaborates. Then once everything is finalized (approved by participants), you can make a check list for each project which can be used in reviews.
This is good.
The comment in the header file describing each function is needed, but it is a separate issue.
What I am asking about here, how do you know what a serial function is supposed to do? That is, where did you get all those functions? How do you know what a stop bit is supposed to look like? How do we figure out what the half bit period is? They have to come from someplace, so where would a novice look to understand this serial function? For example, can we just link to a wiki article like:
http://en.wikipedia.org/wiki/Serial_communication or http://en.wikipedia.org/wiki/Asynchronous_serial_communication
As another example, if we were talking about RS232, we could reference EIA standard RS-232-C
So where do you look when you have to check something on the serial function?
1. No, it is not in the header file. But the author has agreed to put it there. No offense, but you are not getting it yet.
2. No, the requirements are as stated above several times: A) what does it do?
3. No, I am NOT project lead. Circuit soft is project lead, its his project. I am SQE; I just ask "Did you do any of this process? (as described in step 2)"; and then I report whether or not I got an answer.
4. You can do stuff in excel if you want, if you feel it makes life easier. I have no restrictions on the actual mechanics of how folks do their work, I just need an indication that it was done. I advise that you don't make it harder than it needs to be.
This would be the recommended we to go.
The idea is that we start anywhere with a line in the sand. Then we adjust the process to meet our needs.
I think circuitsoft's serial will be just fine, we just want to work through the process on some example at this point, it's his effort, we can use his code. We can also use any other code at the same time, as the process it intended to handle multiple items in parallel. And it is, we had suggests for more items, those just haven't made it any further yet.
Concerning jazzed' comment from #101: the assessment of suitability of a given piece of software based on its point of origin is incorrect. By design, the process should be able to evaluate any software from any source. Any deficiencies in the software are identified along the way. Reaching the "end" of the process means we've either corrected all the deficiencies, or stopped working on it. Even then, more deficiencies can be found and corrected.
In any case we should continue and see how far we get.
PB, not to minimize your job but if this is what your job consists of, then I want your job!!
This is a very simple wrapper around a complex issue. I'm jaded as to "process" because of my employer but I think I understand the underlying basics of quality and specifying a "Gold Standard" although I'm seeing different priorities and needs for the "Gold Standard Process"
Jazzed is correct in that the Spin and PropGCC items need to be separated. The Gold Standard Process linked to earlier does a great job of specifying a coding standard for Spin objects. This doesn't exist for PropGCC and needs to be developed so everyone is coding from the same page. So, except for your 4 questions, 90% of the PropGCC work needs to be done. There is a tremendous amount of coding style and interface standards to agree upon for a PropGCC standard.
I think your questions answer the what is it supposed to do and does it do it questions of a standard piece of code, but those seem rather obvious and trivial. If it didn't do what it didn't do what it was purported to do, then it has no reason to be discussed as a gold standard. Basic functionality is assumed - if I put X into the black box and expect to get Y out the other side, then I better get Y. If you call it an I2C driver and it doesn't talk I2C, then there's a basic problem.
The more important question is the HOW it does it and HOW you get X in and Y out. These are where the Gold Object Standards documents come in and your process doesn't ask or answer those questions. I won't or don't want to figure out a bunch of different API/Interfaces in order to hook things together. I really don;t want a kit that has slotted, phillips and torx fasteners just because three different people went to the store room to get parts and they each have their favorite. I want to use just one screw driver and if I can't, I won't be buying another kit from you.
So far, we have:
1) a standard document outlining coding conventions, API, documentation standards, etc.
2) a process to ask if all the boxes on the checklist are filled in and if others agree they should be filled in - questions asked and answered - this can really be handled by a conscientious coder and a knowledgeable reviewer or two.
A third component to the Gold Standard equally important to #1 above is what objects need to be in the standard set. The library that comes with the Propeller Tool has a mix of essential, nice to have and fun and interesting demos. The essentials need to be up to Gold Standard (I think there are also more "essentials"), the nice to have should be up to a gold standard as far as interfacing API if possible. The demos are fun and interesting but not really needed to be at Gold Standard. There should be a solid set of Gold Standard soft peripherals since that is one of the big selling points of the Propeller architecture. For example, if Microchip or Atmel have a chip with this tyope of peripheral, there should be a Gold Standard Propeller peripheral to match and an app note to show how to use it. Serial, I2C, SPI, RTC, PWM, etc. should have Gold Standard code with app notes. NES game control interfaces, microphone to headphone, Microsoft Joystick support, etc. aren't really Gold Standard items even though they may be interesting to a hobbyist. This is where there is a conflict with some community sourced tool libraries. Great fun and brilliant pieces of code for a hobbyist but maybe not so useful to an Engineer looking to use a Propeller in a new design.
Other than this little contribution, I'll stay out of the Gold Standard Process debate. If it's just 5 or 6 questions that need to be asked and documented during the code development process, I think I can handle that. (I've probably even asked and answered the questions over the years)
When we get to asking how best to come up with API's and support for the various memory models with consistent, standard code, then my ears will perk up again.
Carry on, all, whatever SQC process you come up with should be able to be wrapped around whatever functional requirements and standards are needed to develop solid Gold Standard Objects.
No, you don't. We get paid in hatred, as evidenced by the easily recognizable mob with torches and pitchforks.
The stuff seems obvious and trivial, because it IS obvious when you think about it, and trivial to do NOW, but a huge problem if you don't think about it and it comes back to bite you. Get it squared away early and upfront.
Until we establish the basics of how we describe our highest level requirements, we are never going to get to describing how to go about testing them, and we will never get to looking at code that attempts to pass those tests.
As I may have said before, code standards are irrelevant UNTIL WE GET TO THE CODE. Yes jazzed is correct that spin and C should be handled with different coding standards. We are nowhere near the of discussion code. Leave that to the side till later. Right now I just want to establish out what the project plans to do and how to check if it does that.
Bingo. So, the question remains, how do we determine what its supposed to do? If we don't know that, we can't determine if it does it or not. How do we check? Until these questions are answered, the rest is moot. This very basic early step is often skipped, and doing so is a main contributor to problems and failure.
Process guy braino advises it is not expedient to work on step three until we complete step one.
I don't think "the process" is meant for submitters with malicious intent (although it may work there, too). Instead, I think the "how do we know it does what it's supposed to" is for mistakes such as not sending a stop bit when the transmitted byte ends with a 1, or something like that.
We are not. This is the experiment. At this point, we are learning the process itself. At this point in the process, we want to define exactly what the project is expected to do, so we can test whether it does that.
By doing this step, the author (who is still in the investigation or development stage) will have the necessary information to make the code function. In fact, I would guess that the reason the code isn't functioning is because this step has not be completed (he can let us know after). In the very least, doing this step will make coding easier.
However, the requirements must be codified and ratified, otherwise it is a complete waste of time. Going through the exercise of reviewing code is a moving target without having a list of agreed to requirements.
It was satisfactory to me when I looked. Obviously the requirements are misunderstood because they are not listed in a single place or agreed to otherwise we could both objectively say yes or no.
This is a high level list of requirements.
So, taking what you have listed and expanding on it. Anyone is welcome to comment.
0a) identify needed Gold Standard objects on Parallax's product roadmaps
1) does the code under submission perform a needed Gold Standard function (is there a better candidate out there?) (has the function already been added to the Gold Standard collection?) (is it something that shoudl be a Gold Standard item?)
2) Has it been written to Gold standard coding and API standards?
3) Does it have supporting documentation (internal documentation to code source PLUS an app note)
4) peer review and requirements checklist, mentoring, coaching, debating (lather, rinse, repeat)
5) update standards documents if needed (need to keep backward compatibility if at all possible)
6) Publish as Gold Standard with all documentation
7) identify next most needed object in Parallax's product roadmap
8) return to 1
I think it's clear that the steps they are working on are not the entire process, but they are an important part of the process.
It looks like those steps fit the first part of the process outlined by Jazzed, so how about letting them complete them as an example.
It would be nice to see some action on the other parts mentioned by Jazzed, but who wants to step up and help when it just makes them a target for more rocks?
I'll offer to help with a task or two if Jazzed wants to setup a task list of some things we can do to help with an example of the parts of his list not covered by what prof_braino and circuitsoft are working on.
Let's show how we can work together.
C.W.