Is a short tidy code neccessary ?

Make sure you do a flow chart some time during your clean-up, earlier better then later. Make some optimizations. I wish I could remember my stuff, but my current project is already over 2,500 lines even after quite a bit of optimization. Each time I go back to it I had to spend time figuring out what it going on. I'm glad I have one flow chart for a large part of the program. If I need to go back to that part I'll spend less time reviewing.

Coming from a business point of view, if the code satisfies all requirements and can be maintained easily, I would refrain from turning it into something that would be difficult to maintain easily.

Exactly. And people asking the question about how clean and tidy usually have the part about satisfying requirements done but have big doubts about the easy maintenance part. Having a clean and tidy to code with meaningful comments is absolutely necessary to be able to maintain it. I've suffered so many times from messy code in my career that I can tell, no other way works. Code is only finished once you wouldn't be ashamed of if it was published in the current form.

About code being short, that's usually not a goal to strive for, but it's often just an automatic consequence. If you remove all the cruft and make things easy to maintain, a lot of duplicate code disappears and code will be structured to make things more compact. However, beyond that point, shortening the code further should only be done if you really are running out of space, which is nearly never the case.

So as a general rule, it's absolutely necessary to have clean and tidy code. But don't make code more confuse just to make it a little smaller.

Korman

I was wondering what happened to flow charts, I remember we used to do them when I was messing around with basic in the 80s, but I didnt want to mention them as I saw what happened to the guy who dared to mention gusub :wink:

I downloaded some Yenka program that someone suggested using to (re)learn the flowchart shapes etc, I must have a look, but basically its just getting used to how to picture the instructions, when I was used to the loops and gotos of the basic.

I think I will leave my code as it is, but go through and comment quite heavily, what seems obvious now might seem crazy in a months time.

Make sure you do a flow chart some time during your clean-up, earlier better then later. Make some optimizations.

Liudr,

no to both things.

Optimisations should be done only on code that has performance problems. Don't waste time on optimisations that work well enough. Optimisations make code more complex. Don't confuse optimisation with throwing out the garbage or repairing bad code.

As to the flow chart, that tool was very popular 30 years ago, but has proven to have many limitations and it doesn't work very well for many purposes. A flow chart usually works best on linear code, but that is just as easily documented by putting section headers with in your code. Stuff like:

// Set up the ports.
// The ports are set up in the reverse way to prevent the car
// from backing into the garage wall.
...
... code ...
...
// Check where we are.
// Check near field reception first to prevent acting on imprecise
// long range tactical scanner data.
...
... more code ...
...

In most situations, a clear and easy to read code documentation is preferable to a flow chart. The important things to document is to document goals this block of code achieves and why some non-obvious implementation has been chosen over a more common on. Just by reading the comments you should get a good idea what your code does and what important design decision you have made.

Korman

I will try that, and the flowchart, thanks all

Think of flowcharting like stabiliser wheels on a bicycle.
You'll need them only for a short time.

or like nappies, when you are very young or very old !

As for comments, there's good and bad ways of doing it.

For instance:

BAD:

// Set digital pin 4 high
DigitalWrite(4, HIGH);

That's a useless comment. Anyone with a basic understanding of the Arduino environment already knows what DigitalWrite does. But WHY are you setting pin 4 high?

BETTER:

// De-select the SD card module
DigitalWrite(4, HIGH);

Even better, however, would be to make the code itself clearer and explain why you want to deselect the SD card:
A BIT BETTER:

#define SDCARD_SELECT 4
...
// We de-assert the SD card to avoid SPI bus contention while we use
// the ethernet chip
DigitalWrite(SDCARD_SELECT, HIGH);

Basically, when writing comments, assume that the reader has basic knowledge of the environment. So explain things that are tricky, but don't explain things that are obvious. And, if you can make them obvious in the first place so they don't need a comment, even better. Not every line of code needs a comment (although most programmers write too few, not too many).

I also typically comment any math I do - not something like:

// We divide by two to get distance
distance = sensorReading / 2;

After all, anyone can see that divides by 2. The question people have is "WHY?" (you'll have it in 6 months, too, even if it is your code).

So, something like:

// Distance from this sensor is 1/512 of Vcc per inch, so it's exactly 1/2 of
// the AnalogRead() reading
distance = sensorReading / 2;

Some other tips - use subroutines:

If you find yourself indenting more than 3 or 4 levels deep, you probably need to call a subroutine to make it clearer.

If your subroutine doesn't easily fit on your screen, you probably need to break it into smaller subroutines.

If you are repeating code, maybe only with a tiny change, you probably need subroutines.

Of course there are exceptions to all of these rules (speed is not one, BTW; you can use the "inline" directive when creating a subroutine, which will tell the compiler to "unroll" the subroutine and put it directly in each location of code that calls it - to increase speed). But generally you start with it broken down if at all possible.

Finally, if I'm modifying someone else's code, I try to follow their style, not impose my own (so if they use 8 character indents, so do I, for instance). Other than that, I try to follow the style/formatting I see most often in that environment - that means it's easier to get help if I need it!

Think of flowcharting like stabiliser wheels on a bicycle.

Or the second (stabiliser) wheel on the bicycle...

Then you learn to be a big boy and ride a mountain unicycle :wink:

Flowcharting is still a good tool for planning and discussion (especially highleveled concepts), and also for selling ideas to project managers (and others with a key to the vault;))

Textual source documentation can not be replaced by any models, and the purpose of a model can not be replaced by any textual source documentation.

Formal descriptive models of an implemented systems is of importance when the developer team need reinforcements or maybe replacements.

And yes, short tidy code is neccessary! Unreadable code is definitly not.

Well I am still learning to program, as hardware is more my background. So my approach may be a lot different then many around here. I tend to write my code in small parts, testing things as I go, checking out the external hardware components, etc. So the first complete working program tends to look a little sloppy and probably using too many global variables, etc. Once the overall program is functioning I then tend to take some time to rewrite sections, maybe turning in-line into functions. Then I spend a lot of times on the comments where I try to explain mostly to myself what and why a section is doing. At that time I might then rewrite sections to try and make it more conventional or shorter. As I said I try and learn as I go and so far it's been fun.

Lefty

My long code is definately readable, but like a boring book with 28 identical long-winded chapters ( A-Z . and blank )

I look forward to getting some time to tidying it up as an exercise in how I should have planned it the first time.

Seeing hardware types talking about coding is funny, almost as funny as seeing a programmer with a soldering iron ;D .

Flowcharting only works on small programs, after that you really need to look at something like UML if you want to model your program.

comments can be helpful, but well written code should be self documenting, use meaningful variable and function names, and make good use of indentation and structures like switches.

compact code can be good, but it is possible to make something too compact, for instance:

x=(a==b)?1:2;

is perfectly valid code, but readability wise is absolutely terrible, and will produce exactly the same output as

if (a==b)
{
     x=1;
}
else
{
     x=2;
}

what is easier to read to you?

what is easier to read to you?

It depends. Often the second version, but I've encountered situations where the first was a lot easier to understand and easier to read. I usually use the triadic operator when it's absolutely clear that it's part of the expression and making an if out of it would rip apart an expression that should stay together. Also, in situations where you have a bunch of that kind of expression, the many if statements can make a total mess out of the code. You just have to use the right tool in the right situation.

Korman

I disagree that flowcharts aren't useful. Most people on this forum are not professional programmers. We write most programs from ground up, testing one module and then do some more. When you do it that way and your project grows into a much larger one than original program. If you don't do a model like a flow chart, you're lost at what you're doing especially you don't come back to it every day. At least I'm too old to remember all my details.

If you don't do a model like a flow chart, you're lost at what you're doing

If your code is complex, a state diagram is usually of most use, perhaps a rough block diagram. A flowchart with its very linear structure is a just a bad tool to document. Also, more important than the diagram is a management synopsis of what the program does, what limitations it has and why you wrote it.

Korman

If your code is complex, a state diagram is usually of most use, perhaps a rough block diagram. A flowchart with its very linear structure is a just a bad tool to document. Also, more important than the diagram is a management synopsis of what the program does, what limitations it has and why you wrote it.

Korman

Wait, What? At least I know which end of a hot soldering iron to hold and to not solder with shorts on. :wink:

Lefty

Very good tip that, about the shorts, thanks retrolefty :sunglasses:

Re the flow charts, I reckon the whole idea of Arduino is to get people with little or no knowledge of micros to be able to get into it.

A lot of us probably have had a dabble at basic with flowcharts sometime, and can "see" the flow better.

Experienced guys can probably look at reams of instructions and recognise various routines there, even in the complex programs, but I don't think that's what this forum is about.

I guess most of us newbies are still trying different ways and patterns to light an LED, and perhaps simple flowcharts can help there....

In a commercial environment, probably.

In the stimulating Arduino world of hobbyists, experimenters and autodidacts, no!

I preface all my work with the phrase "It may not be the best way to do it, but it's the way I've done it".

Rgds.