Go Down

Topic: xkcd:  Writing Good Code (Flowchart) (Read 5731 times) previous topic - next topic

James C4S

http://xkcd.com/844/

Anyone else feel like this sometimes?
Capacitor Expert By Day, Enginerd by night.  ||  Personal Blog: www.baldengineer.com  || Electronics Tutorials for Beginners:  www.addohms.com

retrolefty

#1
Jan 07, 2011, 07:55 pm Last Edit: Jan 07, 2011, 07:55 pm by retrolefty Reason: 1
I sure do. My personal definition of 'good code' is any sketch I write that doesn't write red s%#t all over the IDE's output window when I try to compile it. If it actual does what I want it to do, that is just extra icing on the cake.  ;D

Lefty

biocow

Sent to my coworker. We're going through this exact thing with our current project.
10 PRINT CHR$(7)
20 GOTO 10

SubZer0

I certainly do! At work they often like to erase the arrow leading back to 'start project' (as well as the arrow 'right' which leads to code well  ::))

mowcius

Yeah saw this and it sums things up nicely.

Spent ages, doesn't really work right - started again :)

Speeds up code as well as normally making it better.

Divyanshu

|I love Technology|

pwillard

I love that.  I have a reputation of never being done with my coding at the office since I regularly tweak my work.  I think, to be fair, calling code *done* is just admitting you have to give up at some point.

Here's a random thought...

So... since we have so few examples of GOOD posted by the Arduino 101 "students" in the forum... should the more experienced of us also explain what good coding *is* and create some "Arduino style"?




mowcius

Perhaps, who's got the time? You?  ;)

pwillard

Well, I would try to write it *well* and not fast...   which means the requirements will probably have changed by the time I was "done".

Just Kidding.

mowcius

Heh, I don't think it would be ever finished ;)

cr0sh

Honestly, that flow chart is simplified to the point that if that is really what is going on at your particular workplace, you either don't get anything done, or what gets "done" is poor quality and/or difficult to impossible to maintain.

What should happen at all stages are various code reviews and meetings with the client where, if they should change the requirements, are required to sign-off (with a physical, on-paper signature and date) on the changes, perhaps with the understanding that there would be time and cost increases which they -will- be billed for.

Furthermore, there need to be team code reviews, presumably to ensure that the code produced by all team members follows the company's (or team's) agreed-upon coding standards. It should be noted that if there are multiple teams in a company, that there is one coding standard for the company, regardless of which team is doing the coding - because in the future maintenance of the code-base is going to require clear and set standards - which of course also need maintenance, so it should be clear in the code which version of the standards are being used; sometimes in the course of a long project, it may be useful to refactor the code to use the latest standards as well.

These standards should emphasize upon a clear and concise method of coding, with strict formatting rules, variable naming conventions, and commenting practices (a doxygen-based commenting style can do wonders - especially for coding documentation). Failure to follow the practices as laid out in the convention should flag a return to the developer(s) involved, so that they can refactor the code to adhere to the standard and pass the review.

One thing I have found for maintainability of code: Consistent spacing improves readability. An extra space or line break, used consistently, can have a dramatic effect on the understanding of the flow of code. The compiler or interpretor isn't going to care in the majority of cases (Python may be an exception - but its strict rules on spacing and formatting will likely make the code more readable anyhow; anything extra likely won't break much if anything).

The key is "consistency" - all the rules in the world mean nothing if they aren't applied uniformly throughout a process.

Finally - I must interject one other thing I have noticed quite often as a professional software developer is this tendency in some organizations and by some clients to think that design doesn't matter; that software is somehow "magic". In some cases, it has felt akin to being asked by a client to build a skyscraper, but start the building of it from the 20th floor, with no plans. Rarely do such projects turn out to be successful; should they work at all, they likely resemble (internally, from a maintenance perspective) a building from Terry Gilliam's "Brazil", with about the same attendant level of maintenance ease.

Software should be architected; it should be engineered and designed. Ideally, solid frameworks and functionality should come first, with all testing done at these low levels to verify that the functionality is solid and won't cause the collapse of the edifice once it is completed. With such proper architecture, it should be possible to have a design from which pieces can be easily removed and recombined on other projects with little effort (indeed, in the Arduino world, this is the whole point, what with the various libraries and such). Code reuse should be paramount; however, in order to facilitate this, the interfaces to those reused objects should be clear, defined, and consistent across the code base (or at worst, within the library).

Logic flow of the entire process, whatever the process is, should be specified and "run" as a "simulation" by the entire team; this can be accomplished using nothing more than a lot of flowcharts and a whiteboard, some pencils and paper; parts could be augmented using a computer and other tools, but aren't strictly necessary. Indeed, depending on the process being studied, you might end up finding parts of it which are "assumed" and handled by humans - but not detailed in any actual part of the flow. Sometimes things like these are found during the conversion of a manual business process into an automated workflow; as you study and question the individuals involved, you sometimes find that they perform functions which are a part of the process, but aren't defined as such, but are needed to "smooth" the flow. Some of these can be automated, some can't - but they need to be taken into account in the entire process, because the rest of the process may rely on the success or failure of their output into succeeding stages.

Most of the time for many businesses (perhaps most, especially small businesses) these processes (whether internal, or of some software or such) are never defined or architected in some way, likely due to money and time. Somehow, things seem to work - until the burden to the system becomes so large that it fails. Then another bandaid is applied and its hoped that it fixes it, when the reality is that the entire process needs to be understood by people at both a macro and micro level.

/realized I'm rambling, so I'll stop here...  :P
I will not respond to Arduino help PM's from random forum users; if you have such a question, start a new topic thread.

pwillard

#11
Jan 10, 2011, 02:53 am Last Edit: Jan 10, 2011, 02:55 am by pwillard Reason: 1
Quote
Heh, I don't think it would be ever finished


Hehe... that was my point... I know *me*

Crosh...  Nice work...   My opinion is that  we need to sort of find a middle ground between professional and hobby mode.

cr0sh

Quote
My opinion is that  we need to sort of find a middle ground between professional and hobby mode.


Well, probably best for hobby mode (code-wise) would be:

1. Use a clean, concise style
2. Have good formatting
3. Be consistent in your style
4. Use comments where appropriate
5. If needed, create documentation (doxygen-style commenting in the code can help)

:)
I will not respond to Arduino help PM's from random forum users; if you have such a question, start a new topic thread.

pwillard


Divyanshu

cr0sh, How much time did you take to type that much! :P
|I love Technology|

Go Up