Is a short tidy code neccessary ?

By the way, is there any reason why a sketch has to be tidied up if it is working well?

I know there is a lot of pride in keeping it short ( my 2 axis doming machine has only 13 lines ) but I am in a hurry for the current project, and I can have a pcb made and have the thing running with its ridiculously long code, and tidy it up later when I am up to date, for subsequent units. ( I couldn't do that with my CMOS prototypes ! I love this Arduino)

I would be too embarrassed to even post the code on the forum, ( and these pages aren't long enough for all the lines ! :slight_smile: )

For instance every 7x5 display at the moment has its own look-up table for the whole alphabet for the LEDs !

I am updating some of my CMOS logic products to Arduino now, I suppose later I will use the grown up version of the chip , but while it works that's fine by me, and it will save me a fortune in pc boards, both space wise, and also for all the wasted prototypes that I could paper my workshop walls with..

short tidy code can be a double edged sword, make it too short n tidy and it becomes difficult to see whats going on

make it too long winded it becomes burdensome to read debug and sometime execute

OK that's cool, its definitely easy to see whats going on, although scrolling through it makes me rather giddy !

It will do for now, and I can set myself a challenge to see how neat I can make it when I have some time..

Clean and tidy can be a double edged sword, true.
Unclean, bloated code.. however, is a hiltless blade, you'll nearly always hurt yourself with it. Either because it is hard to get help, since it is so bloated, or because it contains a lot of duplicate code.

As with a lot of things, theres a sweet spot in the middle.

code should be like your desk. Neat enough for you to be able to find the things you're looking for without much trouble.
Exactly how neat this is varies quite a bit from person to person.
It really sucks to go back to an old program not not be able to understand what you were doing...

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.

That said, if I was sharing my code with others, a bit of professional pride would require me to make sure it was clear as to what I was doing. If I thought I'd need to maintain it, the same goes.

As for optimization, if I have 32K of program memory, I don't mind using 31K of it - so long as I can fit everything I need into the RAM.

code should be like your desk. Neat enough for you to be able to find the things you're looking for without much trouble.
Exactly how neat this is varies quite a bit from person to person.
It really sucks to go back to an old program not not be able to understand what you were doing...

Good thing my code's neater than my desk ;D
But only slightly...

Mowcius

now and again I hold a box at the end of the desk/bench and "scroll" everything off. A control +T tidy up function would be great for the desk..

My mile long code, by the way, only uses half the memory .... so as I am using Shiftout to 10 display characters, and they all come on in a random pattern, I might as well have my brandname showing when it is switched on, which I think I can do in the setup...

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.