Go Down

Topic: Is a short tidy code neccessary ? (Read 2619 times) previous topic - next topic

Joel Maslak

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

For instance:

BAD:
Code: [Select]
// 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:
Code: [Select]
// 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:
Code: [Select]
#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:
Code: [Select]

// 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:
Code: [Select]

// 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!

mowcius

Quote
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  ;)

AlphaBeta

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.

retrolefty

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

Boffin1

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.
With my mobile phone I can call people and talk to them -  how smart can you get ?

UltraMagnus

#20
Oct 25, 2010, 10:43 am Last Edit: Oct 25, 2010, 10:43 am by UltraMagnus Reason: 1
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:

Code: [Select]
x=(a==b)?1:2;
is perfectly valid code, but readability wise is absolutely terrible, and will produce exactly the same output as
Code: [Select]
if (a==b)
{
    x=1;
}
else
{
    x=2;
}


what is easier to read to you?

Korman

#21
Oct 25, 2010, 11:44 am Last Edit: Oct 25, 2010, 11:46 am by Korman Reason: 1
Quote
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

liudr

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.

Korman

Quote
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

retrolefty

#24
Oct 27, 2010, 02:33 am Last Edit: Oct 27, 2010, 02:34 am by retrolefty Reason: 1
Quote
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.  ;)

Lefty

Boffin1

#25
Oct 28, 2010, 10:57 am Last Edit: Oct 28, 2010, 11:05 am by John_Smith Reason: 1
Very good tip that,  about the shorts, thanks retrolefty 8-)

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....
With my mobile phone I can call people and talk to them -  how smart can you get ?

Selby96

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.

Go Up