Page 1 of 1

Required Reading For All Members Of This Site

Posted: Thu Jul 03, 2008 1:05 pm
by Fred
Preface

Some of my valued members have been complaining (quietly) that this project is "Fred's project" and not an "Open Project". This is partly an attempt to explain that feeling and partly an attempt to describe the way FreeEMS is being developed and why that is the case. Even more valued members have been complaining about the behaviour of one member on this site. I will attempt to make it clear what is and is not OK on this site.

Development Methodologies

I've been trying to articulate to some people here exactly why the product development is occurring the way it is. I've been studying up on some development practises in preparation for a job (and it's interview, but that is secondary). Some of the material I have come across in my reading travels is directly applicable to this project.

Obviously because the EMS market is old and well defined there is little room for the basic requirements to change. For this reason some aspects of these methods are not AS beneficial here. However many of them are ALWAYS beneficial. The market may be well defined and unchanging, however our ideals about what an implementation of an EMS are far from static. I will attempt to illustrate this principle for you.

Traditional software development involves a large up front design which is then broken down and implemented. This is fine if you really know exactly what you need. I have some good ideas about what I need, as do some of you, however none of us, me included, know exactly what we want right from the outset. This means that the traditional cumbersome approach will cost man hours. Software that is written to the design when the actual requirements do not match that design is work wasted. Traditional methods are also only really applicable when you have two things : time and resources. We have neither. Finally this is how traditional software development attempts to work :

http://www.inter-sections.net/2008/05/1 ... -not-exist

Instead of that, a now 12 year old practise and it's 22 year old cousin are strong favourites where resources (my time) are scarce.

The 12 year old practise is called XP which does not stand for a mediocre Micro$oft operating system (stretching the term), but rather eXtreme Programming.
The 22 year old practise is called Scrum and named after part of a game called Rugby.

These are both similar practises under the same umbrella known as agile software development.

Firstly, some of you are wondering why the project seems to be "my project". This is ONLY because I am doing ALL the tangible work. If someone else with similar ideals to myself and sufficient talent and care for the project stepped up and started submitting code to me, it would instantly cease to be "my project".
So the pigs are committed to building software regularly and frequently, while everyone else is a chicken: interested in the project but really irrelevant because if it fails they're not a pig, that is they weren't the ones that committed to doing it. The needs, desires, ideas and influences of the chicken roles are taken into account, but not in any way letting it affect or distort or get in the way of the actual Scrum project.
Here is why I make the decisions on the designs, goals and code that I write :
Pigs are the ones committed to the project and the Scrum process; they are the ones with "their bacon on the line."
Hence, I care a great deal about what my code is like and I try to ensure it is the very best it can be.
Chicken roles are not part of the actual Scrum process, but must be taken into account. An important aspect of Agile approach is the practice of involving users, business and stakeholders into part of the process. It is important for these people to be engaged and provide feedback into the outputs for review and planning of each sprint.
This is both me (funding it with my time and money, and caring about what it does too) and all of you. If you genuinely care, do get actively involved with discussions on what is going on with respect to what the code does and how it does it. We both want the very best at the end of the day.
Customers become a part of the development team. (i.e. the customer must be genuinely interested in the output.)
This is a MUST, if you don't care, what are you doing here? Jean cares, Abe cares, Stu cares, I care, If you care, post your thoughts. Do not be afraid of offending me with them. If they are purely technical and formed in a straight forward honest way they will be received with open arms.

Scrum roles

Now, that's the relationship you and I have with each other. You either get stuck in and code, or you get stuck in and share your thoughts on the code etc. What about how I am going about producing a functional EMS in the least possible time at the highest possible quality? Some would argue this isn't possible. My opinion differs.

To ensure minimal wasted effort, the fastest path to the goal of a working tunable fuel injection and ignition computer I do the work in blocks of discrete and distinct functionality. I do these blocks in a minimal way such that the least possible effort is wasted on developing something not fully understood.
During each sprint, a 15-30 day period (length decided by the team), the team creates an increment of potential shippable (usable) software. The set of features that go into each sprint come from the product backlog, which is a prioritized set of high level requirements of work to be done.
Our high level requirements :

http://issues.freeems.org/roadmap_page.php?project_id=1

For example, I started by
  • Laying out the memory files and some basic source files etc.
  • Added PLL initialisation
  • Added bit banged IO
  • Added ADC reading
  • Added PWM output
  • Added ISR handling
  • Added Input Capture IO mimicing for JimStim signal
  • Added Output Compare IO based on input
  • Added Real Time Clock
  • Added Low Voltage detection and counter
  • Added Modulus Down Counter timer use code
  • Added PIT timer code
  • Added serial comms in ASCII
  • Added input tables and VE tables and input conditioning code
  • etc.
Clean minimal blocks that can be reused or thrown away at will. All the code is in clean files and functions and chunks with decently defined interfaces of the manual variety. If any aspect needs more work, it shouldn't affect any other aspect. If any aspect needs to be replaced it is not a big deal. Ideal really. And it has been proven to be ideal. I've replaced removed rearranged and refactored most everything in there at least once to improve it and make it work with things I hadn't seen at the time. Being able to do this is important.

In the image below, the 15 - 30 day circle is my release pattern. So far we are at about 6 months with 14 releases of varying size. The 24 hour loop is this forum where you post and I post and we discuss what is happening and going on. For that there is my firmware diary thread :

http://www.diyefi.org/forum/viewtopic.p ... ead#unread

And the comments thread for it :

http://www.diyefi.org/forum/viewtopic.p ... ead#unread

And of course all other more specific threads on stuff like serial comms, table size, variable min count, wheel reading, adc sampling, etc etc etc.

Image

To ensure that through each dev iteration focus is not lost the following are adhered to :

http://en.wikipedia.org/wiki/Extreme_Pr ... Simplicity - of the code means it is understandable, comprehensible and readable. It also means that the least work possible was done to produce the code so if it is wrong/bad there is less lost by.... :

http://en.wikipedia.org/wiki/Extreme_Pr ... ng#Courage - to change and remove my code when I see a better way. I constantly do this. With more experience gained on a particular aspect I see a better way, think about it, and wholesale replace the code if required. I have no problem doing this if it is required to be done to produce the best code.

So, this works really well because A we don't have much dev time/resource, B we don't know what we really want, C effort is only invested where it is truly required, D when we find something is wrong it is less wasteful and easier to change etc.

Designs are important too, and are certainly present here in many forms and are spread out fairly widely. Don't make the mistake of thinking designs are not present. That is simply not the case. If you need a reference for a particular aspect and can't find it with searching, feel free to ask for it, or even better, volunteer to produce it.

So, what's missing : Unit tests!
What replaces it : Functional testing, Logging and analysis, specific code written to test other code internally, peer review of code.

This is the ONLY way to go on these embedded cores unfortunately. I deeply miss being able to wrap code in tests and either be able to fix it deterministically or enjoy the 100% passed green light and know my work is solid. Embedded = a lot of guess work. Others use a BDM to open the box and watch it run, I use clean code and a solid understanding of what it does and the implications of that.

This is the way it HAS to be, and I strongly believe that this is also the BEST way to approach this. When I mentioned XP to a friend of mine in early February I got the following response "i am familiar with the term, but never really understood it completely" I hope this post clears XP and it's use on this project up for him and everyone else too.

Free, Freedom, Open, Open Source

Free refers to many things. In this case it refers to the following :
  • Free to say what you think about technical aspects of this project
  • Free to disagree about technical aspects of this project
  • Free to pick up the ball and run with it by coding and designing and working this project in real ways
  • Free to your opinion of whether or not various goals and desires desirable
  • Free to take any of the GPL/BSD/TAPR work from this site and use it in any way you want and share the results
  • Free to modify, change, play with, reimplement etc
  • Free to use the code on different hardware to standard
  • etc.
All of those are true and have always been true.

Open refers to many things too. In this case it refers to the following :
  • Open development with all details exposed
  • Open source available for you to read and change
  • Open source available for you to take and do what you wish with
  • Open to all people including Lance to share their thoughts
  • Open goals, plans, designs, documents, etc
  • Open to you joining and helping as several of you have
  • etc.
All of those things are true and always have been true.

What they don't mean. Some examples of what an open free project does not involve or mean :
  • You are NOT Free to command the person doing the work to do it your way (you can suggest, but you can't complain if they don't, if it doesn't suit you, do your own)
  • You are NOT Free to behave in a way that negatively impacts other users experience on this site
  • You are NOT Free to post in an off topic way on purpose where it is not relevant
  • You are NOT Free to post in a way that is clearly trolling for emotional response
  • You are NOT Free to ask questions to which you know the answer
  • You are NOT Free to wilfully post misleading information when you know it to not be true
  • You are NOT Free to intentionally start arguments (which differ from debate and discussion)
  • You are NOT Free to assume that you have the right to access to this site
  • etc.
IE, please use some common sense. If you actively desire to cause trouble, waste time, derail threads, distract users from the task at hand, expose others weaknesses (we all have them, make no mistake) etc etc etc, do not even bother to try. I will not tolerate it and my users should not have to tolerate it. This goes for ALL members.

This site and the people it contains did not come cheaply to me. I put a LOT of work into making it a great place to hang out and talk about engines and making them go. It took a long time and a lot of effort to bring the site up to publishable spec and to make the forum a useful workable place. Without these things the userbase would not be as big as it is now.

I want to share this privilege with everyone, however do remember that it is a privilege and NOT a right. If you abuse it or misuse it I will be forced to act. In future if I receive any justifiable (I can see that they have a good case for their claims) complaints from any user about any other user a warning will be issued. 3 strikes and you are out may be a good strategy? From 150 users I've only had real problems with 4, one left on his own accord, one is running on borrowed time, one is showing promise of improvement, and the last one may be the same one that left on his own accord. The user running on borrowed time should watch his step carefully as no further indiscretions will be tolerated.

Thanks for reading!

Fred.

Re: Required Reading For All Members Of This Site

Posted: Tue Jul 08, 2008 9:13 am
by Fred
Another article that some people here should read :

http://c2.com/cgi/wiki?WhatIsSoftwareDesign

Fred.