how do you plan / document larger AVR software projects?

Go To Last Post
6 posts / 0 new
Author
Message
#1
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

I am not sure if this is the right place to post my question, but my question is about planing and documenting the software on an AVR you are working on - or going to work on.

I find that the larger the project gets, the more nested the routines the more difficult it gets to keep a general view on what is going on.

I think that the C++ and its objects help to keep well organized but it is not THE solution.

And then you all know that felling get looking at your code a couple of months later and thinking what did I intend here?

 

So I have come to a conclusion that i need to start documenting better, apart of the remarks in the code. I think I need a general flowchart for the broad picture of my software but also some way to document other routines. What is a good way to do it? What are your experiences? How do you do bigger projects or in cases where you are not the only one coding - or if you want to be able to understand your code months or years in future?

 

The reason that I am asking myself this question is that I am working on a project with a touchscreen, menu, CAN bus and some kind of multitasking.

 

Your comments are appreciated.

 

Leo

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

I use Doxygen to document my code. Note this is not specific to AVR - it is a common software development problem. The book 'Code Complete' might be a good read. You might want to institute a coding standard.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Software used to be an art or a craft like making pistols. Samuel colt sort of standardized the pistol making with interchangeable parts, but software was still an art. If you got a bunch of civil engineers and mechanical engineers in a room and told them to design and build a bridge, there were metrics. It takes 40 D size drawings to get the design done. The boss can look in the big drawer and count the vellum drawings. If there are 30 of them, the design is 75% complete. If you put a couple of programmers in a room and tell em to write a program, and come back and check on them every couple of days it sort of goes like "How that program coming?" "Almost done! Just two more edits!" and this goes on for weeks. Maybe months. So Software Engineering was invented to try and convert programming from an art to a science. But there are good and bad artists and good and bad engineers. Some more prolific and productive than others. There are sw engineering Best Practices. I hope I dont get the process embarassingly incorrect, but a project needs requirements. What it should do. Maybe a Use Case that describes what the program user sees on the screen. The customer tells the sw engineer the requirements. The sw engr converts the reqs into a proposal. What it will do. At contract award, the proposal gets converted into a spec... how its going to be done. This is the stage where tasks and modules and their interfaces are defined, and software timing and sizing of the modules is predicted, and processor choice based on software timing and sizing predictions are made. Then you need to know when it is done. When you get paid. The Acceptance Test Procedure is a matrix that can trace every reqirement to the spec. Need a debug process in there somewhere. When someone says this isn't working right, is it working as designed, and a new requirement is appearing? Or its a hw problem or a sw problem? Who determines the problem is fixed is sometimes a problem. Phew. Its complicated.

 

Imagecraft compiler user

Last Edited: Mon. Apr 6, 2015 - 01:04 AM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

 

 

 

 

 

Last Edited: Mon. Apr 6, 2015 - 02:56 AM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

That's deep, Doc.

 

2 82,589,933 -1 The largest known Mersenne Prime (Dec 7, 2018)

"If you think you're always wrong about everything, look on the bright side. You're probably wrong about that too." -- Ziggy

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Actually, he had a nice succinct bulleted list of design steps and milestones that were completely appropriate to the subject title. Somewhat less mumbo jumbo than software engineering speak.

 

Imagecraft compiler user