How do you program your Programs? Flow Charts, Top/Bottom or Bottom/Top?

PoundSign2

Hello friends! While I haven been at the forums for a hop, skip and a jump, in other words not long at all, I have come to learn many things and participate in some good conversations. There are examples for this type of code, how to use this code, how to hook up this component or how to read this or that. Essentially what I see is a lot of programs and code. However I see nothing in the way of how to program. Specifically how to Program and use SPIN. I don't mean the syntax, what I mean is, how do you design your programs? Do you use a flow chart? Do you get out pencil & pad and just write it out? What exactly, are we doing to program our programs?

To be fair there's a bajillion tutorials on how to use white space, how to indent and make our programs look pro or fancy. But where is a good, solid method or methods on how to build the program in the first place? Do you start with the result and work backwards or do it like a book and go from left to right top to bottom? Do you use a lot of comments or do you use little bits here and there so there's less clutter?

I would just like suggestions and documentation on how we as a community go about punching in the code and how we come up with our programs. How does someone know to create this variable or that variable, to call this function or method? Often I have a project or goal in mind, but no clear or obvious way to program something to get the proper result. If I knew how to tackle these methods better I might be much more efficient at programming. As a beginner and a newcomer to the community, I feel that myself and many others might learn a lot more if them and & knew how to get the program going in the first place, and once we start typing syntax, how to best structure it and set everything up.

If there's a thread on this I apologize but the search function did not result in any matches.

Heater.

PoundSign2,

Here is a sort of example of how my program building goes on the Propeller.

0) I have some vague notion of what I want to do. Most likely not written down at all.
1) OK I need a serial I/O interface, let's get that working.
2) Also need an LCD interface, let's get that working.
3) Looks like some file storage might be cool, get that working.
4)...repeat for as many small parts as required.
5) Ah..now I can stich all thise little working parts together and get my vague notion working.
6) Damn, these things don't fit together quite how I like go back and fix them up, improve their interfaces or whatever.
7) Damn, this kind of works but I would be embarassed to show it to anyone, it's a big jumbly mess, rewrite the whole thing.
8) Repeat 7) a few times.
9) Start thinking about optimizing for speed or size if either of those are a problem.

Profesionally things are supposed to be more organized. There is a requirements document that many people have approved, Many of those steps above are worked through in a design phase where you try to find all the problems before you start coding.

Secretly, a lot of profesional development I have seen goes as per my outline above:)

All in all it comes down to writing a lot of code. Making a lot of mess and mistakes. Eventually it dawns on you why global variables are not a good idea, or GOTO should be avided, or objects are a neat way to organize things. You get a feel for partitioning a design in to independent testable units of some form or other. And so on.

Flow charts can help, even if they are considered old fashioned. But then there are state transition diagrams. Structure charts, UML add nauseum. You will get a feel for what is useful when.

Heater.

PoundSign2,

Often I have a project or goal in mind, but no clear or obvious way to program something to get the proper result.

From what you are saying I get the idea that you should scale down your ambition for a while and start with playing around with smalle things first. You have a disconnect between project goals and coding knowledge.

It's like someone who has never driven a car wanting to drive across the country.
First they have to learn to drive. Learning to drive proceeds in baby steps. Starting the engine, stopping the engine How do stop, how to go, how to change gear. how to slow down for corners. Then all that complexity of roads, traffic signs, regulations other road users etc etc etc.
After much practice the driving student becomes fluent at all that. Then one day they can decide "I want to drive across the country" and it just happens.
The project then is not the details of driving but route planning, finding gas stations, places to stay, things to see etc.

In short, start small, practice a lot. Getting little simple things working builds confidence to tackle bigger things.

lanternfish

Hi PoundSign2

I suppose I start with drafting my project in an A4 notebook This usually begins with a block schematic of inputs and their data types/ protocols.

I then search this forum and the OBEX for info from similar projects and methods.

And then I start gluing it all with two hard learnt lessons in mind:

1) All variable, constant, array and names should be comprehensible to someone else looking at the code at a later day. By doing this I hope I can come back to my code without too much scratching my head and wondering what a variable or whatever name means. Not always easy.

2) My notebook contains flowcharts of how the program (is supposed to) work(s).

Some on here use state machines as well.

And most of the time this has proved a god send when I have to fix a fault.

And when all else fails, have a beer and read the forums.

Phil Pilgrim (PhiPi)

If I've learned anything in my 40+ years of programming, it's to do it a little bit at a time and to test each part as I go. Keying in an entire Great American Novel before trying any of it is a recipe for frustration. The key to my sanity, at least, is to write a little, test it; write a little more, test it, write a little more, test it, ..., etc. That way, if something goes wrong, I'll know right away where the problem is.

Other than that, I compose my programs at the keyboard, I don't use flowcharts (a total waste of time), and I add comments -- very important for PASM code -- after the fact.

-Phil

Heater.

Two important rules:

1) Read the book "Clean Code" and or watch a bunch of videos about clean code on You Tube.
2) Don't listen to anyone who tells you there is one methodology or technique that will solve all you software creation problems.

Heater.

If you are going to write anything non-trivial in assembler it can help to write a version of what you want in C or Spin or whatever high level language. (Not to high like Python). When that is tested and working use it as a pattern to write the assembler version. This way you can sort out all the problems in the "how do I get what I want" logic more easily in the high level language, it may even make knowing what you want more concrete.

WBA Consulting

Some might say my "whiteboard" addiction is unhealthy, however, I only sniff the markers because I bought this set. .

Anyhow, I almost always start with visual brainstorming on my whiteboard. It helps my mind work out the difference between the steps I need to take and those fly-by thoughts that are not critical to the finished project or the design process. I have actually killed many of my ideas by working out block diagrams or other notes on my whiteboard in the first stage of just getting the idea written down. After that, my projects take two paths: Either "code and go" until it's completed (or killed in the process) or a complete flowchart/block diagram with phases of the project mapped out so that I stay on track for a deadline.
I utilize these two concepts:

• Develop code within fragmented functional milestones like Phil mentions (IE: one object at a time to eliminate headaches along the way)
• Do what you can to keep your code clean and commented from start to finish. This has saved me countless hours, especially when projects are stretched over months or not continually worked on.

Heater.

Ah, how could we forget? The whiteboard. The most crucial software design tool ever invented!

Especially useful if you have someone else around that you can explain your ideas to. Simply trying to explain the thing can bring problems to mind or if you are lucky solutions as well.

Heater.

How does someone know to create this variable or that variable, to call this function or method?

You know...this is a very deep question.

After many nights of designing, hacking and testing our Propeller coder may have 32K of EEPROM full of his latest creation. That is 262144 bits that have been set to zero or one.

One could look at that and determine that in the act of coding a quarter of a million decisions have been made! For each bit, should this bit be a 1 or a 0? And that's only a small MCU program.

Conversely, one could look at it and ask "That's 2 to the power 262144 - 1 possible programs our coder could have chosen from, how the heck did he come to choose that one?"

Given that we use assemblers and high level languages we clearly did not make all of those decisions. But it's still a huge number.

Now I'm starting to wonder: How do we ever get started?

For a more concrete answer to the question. Variables, functions and objects mostly suggest themselves from the problem you are trying to solve.

Let's say you are building a weather station. You have sensors for temperature, wind speed, rainfall, humidity, etc.
Straight away that suggests you might have objects in your code called "thermometer", "anemometer" etc which are going to deal with taking readings from those instruments.

Then you might consider that you thermometer should have methods like "temperatureNow", "temperatureMax", "temperatureMin", there is always something to initialize so we will have "init". We will want to reset those max and mins so how about a "reset" method.

Similarly for the other instruments.

Of course those instruments are kind of abstract, they may need to talk to the real hardware sensors via I2C or SPI or whatever, so lets have objects for I2C, SPI, whatever. They will suggest their own set of methods.

When you start putting this together you have some data. Well, what are you going to call temperature readings? How about an array of readings called "temperatureReadings" And so on, and so on.

Code just writes itself

bill190

1. Think about what I want to do.
2. Start with programming one thing.
3. Test that one thing.
4. Modify that one thing until it works as it should.
5. Test to be sure that one thing works in all situations.
6. Go on to programming next thing which needs to be done.

So say you have a key pad to enter numbers, a microcontroller, and a display. And you are programming a simple calculator which can add two numbers, display these numbers as they are entered, and display the answer.

One of the first tasks is to be able to enter a number and have the microcontroller be able to "see" it.
Another task is for a number to be displayed on the display.

More than likely, you may try programming number entry, you try it by pressing the number one, and the microcontroller "sees" a 4 (instead of a 1). So you then need to figure out what is wrong.

Anyway just break everything down into tasks and do the programming for each and make sure it works, then put it all together.

So far as variable names, with a small simple program, you can get away with variable names like VarOne, VarTwo, etc. But with a program which is thousands of lines long and may have upwards of a hundred variables, something more descriptive can be a BIG help for troubleshooting and tracking down problems. Like a variable called VarVolumeLevel pretty much says what it is for.

Phil Pilgrim (PhiPi)

One other thing: never be afraid to scrap what you've done completely and start over. Sometimes you just have to do something wrong before the right way occurs to you.

-Phil

David B

My first step in writing a new program is to start by making a copy of a similar existing program, because the great majority of the little detailed utility tasks have already been developed and tested. That way, the new program is sometimes not much more than just a few functions added to an existing structure.

I pretty much never can name functions and variables properly on the first pass because I don't fully understand either the problem or my solution until I've worked on it for awhile, so renaming code parts to make more sense is a normal part of my program development.

Duane Degn

I've learned a lot from reading other people's code.

Phil, Mike Green, JonnyMac and Kye are my favorites. (I'm sure there are lots of other good examples (like Tracy Allen) but I mention the programmers I have the most experience reading.)

I've learned a lot from JonnyMac's SpinZone articles (link in post #3 of my index) and programs. I've also learned a lot from Phil's S2 object. Mike Green's various Basic programs written in Spin have lots of great examples of how to do things in Spin.

I have a hard time following some of Kye's stuff (I've recently tried to figure out how the CMUcam4 firmware works) but I still learn a lot by trying to understand it. I think Kye is fanatical about code size since he often works on such large projects. Some of his shortcuts are hard to follow.

IMO, There are a lot of bad examples of code in the Propeler Library. There's a lot of stuff which was written early on and not improved later when the programmers had learned better technique. There are pin number hardcoded into some of the objects and there are even pin numbers which can't be changed easily because of the way they are used in the source field in PASM (the pin mask is hardcoded which limits the mask to 9-bits).

I mention the issues with the Library objects to talk you into choosing other examples to study.

You'll save yourself grief if you only change pin states from one cog. Pick a cog to control specific I/O pins, and don't let any other cog directly modify them (unless you're sure you know what you are doing).

ElectricAye

I try to do things using a modular approach. As has been stated already, write a small section of functional code, then test it.

Also I comment things like crazy. I very often leave projects for months or years before I need to look at the code again, so comments are essential.

I use variable names that read like short biographies. The Propeller's SPIN language allows variable names up to 30 characters. IoftenUseEveryCharacterEyeCan .

lanternfish

Phil Pilgrim (PhiPi) wrote: »

One other thing: never be afraid to scrap what you've done completely and start over. Sometimes you just have to do something wrong before the right way occurs to you.

-Phil

Oh so true. My current project is on it's 5th iteration and has fewer 'components', both hardware and software and is substantially different from what I first dreamt up.

Genetix

Everyone has their own way of doing things and simple or straightforward things don't require extensive documentation. On the other hand you want to provide enough documentation so if you should come back to something in the future you won't have re-do it all over again. You can do whatever you for your own personal projects but I firmly believe that you should document everything that you do for work. I can't stand having to work on something that has poor or no documentation. Yes, it's a major pain in the a$$ but when you work in a regulated industry it's required and frankly it's just good practice. You can learn a lot about a person by looking at the documents they have created.

Duane Degn

ElectricAye wrote: »

I use variable names that read like short biographies. The Propeller's SPIN language allows variable names up to 30 characters. IoftenUseEveryCharacterEyeCan .

Same here. I was kind of feeling silly about some of my names until I saw I was in good company.

This is from the section of Kye's CMUcam4 firmware I had open.

com.writeString(@aknowledgeStringWithNewLine)

Below are the last three variables in the code I'm working one.

byte terminalState, programNameBufferIndex, updateDisplayFlag

While we're discussing programming in Spin, I'd like to add my support for Parallax's Gold Standard conventions. I'll take useful code in any format it's written but it would sure make my life easier if people (particularly the programmers previously mentioned) used the same convention with method, constant and variable names.

Phil Pilgrim (PhiPi)

On more thing: when debugging, it's always tempting to look for what's right with the errant code, IOW thinking, "This should work because ..." You'll never get anywhere that way. You need to be looking for what's wrong with it. If it helps, pretend that someone else wrote the code. That way, you'll be suspicious of everything.

-Phil

ElectricAye

Phil Pilgrim (PhiPi) wrote: »

... If it helps, pretend that someone else wrote the code. That way, you'll be suspicious of everything....

Imagine I wrote it.

That should keep you on your toes.

idbruce

As I see it, there are two very important questions to consider when writing programs:

1. Will anyone besides me be reviewing or using the programs I write?
2. How complicated will the program be?

If the program will be utilized by someone else or if the program is going to be very complicated, it is best to use a lot of comments. There has been many times that I have reviewed code that I wrote many years ago, which lacked adequate commenting, and this made the review of the code much more complicated.

Some programs are very simple and others can be extremely complicated. If the code is going to be complicated, I often find it easier to write a brief outline of my intentions and key aspects of the program, and then I write my functions to perform the key aspects. When writing functions or methods, I almost always ask myself whether this function or method can be used in another program, and if appropriate, I will make it more generic, so that it can be more easily adapted into another program.

As you build your programming skills, your style will change according to your needs, and only you can determine your needs.

Like many others here, I have also been programming for many years, but since participating in this community, my style has of programming has changed out of necessity and the desire to become a better programmer. One of the discussions that truly affected my programming style was the discussion of the Gold Standard for OBEX objects. There were some very good ideas behinds these discussions that will help you to become a better programmer. I would suggest reading what others had to say about the Gold Standard topic and this will help you to establish a programming style.

Bruce

NWCCTV

I agree 100% with what Phil says. A little at a time so if there is a problem it can easily be found. Flow Charts foe some large organizations are good, but for most people they do waste a lot of time. I basically figure out what I want/need to do and jump in. I also wait until the program is finidhed to insert mycomments, unless it is a really long program and I need to keep it organized for my own sanity.

Genetix

Phil Pilgrim (PhiPi) wrote: »

On more thing: when debugging, it's always tempting to look for what's right with the errant code, IOW thinking, "This should work because ..." You'll never get anywhere that way. You need to be looking for what's wrong with it. If it helps, pretend that someone else wrote the code. That way, you'll be suspicious of everything.

-Phil

That's why it's always a good idea to have someone else look over your work. They might find something that you missed or show you a different way that you can do something.

Cluso99

It's way too long ago to describe how I learnt,or in fact how I taught proggramming. So much has changed.

Start with something simple... turning a ledon and off. Then two leds. Varythe time they areon. Binarycount with some. This islearningthe basics. Keep extendingthis until youhave to rewriteit. Now putthe routines into subroutines andcall them with parameters.

Remember,you haveto start somewhere. Andmake sure you document it -at least this makes you remember what you did. Later you will realise youneedless comments,but a summary of what agroupof instructions are doing.

sorry about lack of spaces -my xoom misses them :0

kwinn

I start with a brief description of what the program is supposed to do and then add the individual steps needed to accomplish that in point form. These points become the main comments for each block or subroutine in the program.

Beau Schwabe

Coding will usually be a compilation of many different thought processes that enable you to get from point A to point B. Along the way I may sketch something out on a napkin, or even in the sand, sometimes I make a flow chart so I can visually test the logic flow of the design on something outside of my head, and other times I will create a state machine which in my opinion is just another style of flow chart. Most always, you start out small with a simple idea and build up from there...

1) Find what works (experiment, read data sheets, study other code)
2) Simplify #1 for your application (remove redundancy)
3) Encapsulate #2 ; make it a SUB routine/function
4) Move to the next section/function/feature of the code and repeat step #1

Note: #4 can often stand alone as a derived function that calls other more simplistic SUB functions to achieve a more complex function.

PoundSign2

Wow thanks for all the information everyone! It took some time to read all of the posts and digest/note the techniques some of you were suggesting. The one I think I found most obvious yet never implemented (on my part anyways) was constantly checking the code while writing little bit by bit. Is there any software out there that specializes in flow-charts or help get your program noted. Such as software that might help you with flow control or something?

One thing I often come across is what I want to do, but I am unable of how to actually program that function. The Propeller Manual serves as a great tool, but often I have no idea what syntax to even look for. Is there a method that you have for overcoming this? I'm sure it decreases with time as your knowledge improves, but for the beginner sometimes it's a pain in the butt trying to code something when you aren't sure what code to even use. Any insights for solving that would be appreciated. Although I don't think there exist a strategy other than learning over time, but oh well.

Heater.

I would not think about any GUI design tools. Over the years there have been attempts to create such things, none very successful or useful.

I have no idea what syntax to even look for. Is there a method that you have for overcoming this?

Not really. Recently I had to do a lot of work in JavaScript for the first time. Despite the fact that JS looks a lot like plain old C it has a lot of higher level features over C and a lot of quirks. Programming in JS requires a very different style than C, that I have used for years. Then there is the issue of the environment, all those facilities in the browser that you can use or all those libraries you can use for server side JS.

It was all new to me and like you I had no idea where to start. So I know how you feel.

Here is what I did:
1) Find as many JS tutorials as possible and read them.
2) Try out all the little examples in those tutorials, play with them. make changes, break them;)
3) Find libraries and modules that look like they might be useful. Read their docs, try out their examples, break them:)
4) Try making my own little programs, starting very small. Experiment with those.
5) Find other peoples code and have a read of that. Be aware that much of it is Smile written by people who are not so skilled. Reading the source of libraries is general a good place as their authors tend to be more experienced. Get a feel for common practices and idioms in the language.
6) Lots of experimenting.

After some months I got my project working. after a year I can see how badly I did it and want to rewrite it from scratch!

All of the above you can do with Spin or C on the Propeller. The OBEX is full of code to study, some of it is rather complex but a lot is fairly straight forward. The Prop manual is a good starting point if you try out all the examples and make sure you understand them

Starting out programing can be very daunting. It's like playing chess, so many possible moves you can make but which one? Every move you make gets you deeper into a situation you might not want to be in!

The only thing that helps is playing a lot of games and studying the games of others.

Mark_T

I suspect that often I start tackling the most interesting part of the code first, the part
that's got me thinking, or which uses a clever algorithm - this is the initial motivation,
and may be a prerequisite for the rest of the project.

Having committed to getting the first part working and tested, the more boring stuff
is motivated by wanting a working whole - unless something more interesting crops
up and diverts you (pangs of guilt!)...

And whether the most interesting part is low level or high level rather depends - often
low-level with the Propeller since you are probably trying to interface to high
speed hardware - for instance my recent forays into driving SDRAM.

For the less experienced I suspect the order is more dictated by where understanding is
strongest, the part of a project that can actually be visualised in the mind's eye.

Moskog

Hey, when I do programming my projects I never remove older versions, always save changes with new filenames. Unless the changes are very small. But keeping lines of code that you think you won't need anymore could be useful too, when testing and debugging. I keep them for a while by uncommenting them until I'm sure they won't be used anymore.

Heater.

Moskog,

when I do programming my projects I never remove older versions, always save changes with new filenames.

And that is one sure way to get into a confusing mess of chaos. After a while one forgets which version of what works with what other version of what else and why you did whatever.

I guess PoudSign2 is not at that stage yet but after a few years of trying to remember what the hell one did and why one realizes that a version control system like git or mercurial or whatever is a good idea.