Documenting embedded C code

cdocumentationdocumentation-generationembedded-systems

I am starting a startup and myself and my partners are having trouble keeping up to date on each other's code and how to implement their functions. Our code is very well commented, but each of us have over 100 functions written, and we are getting to the point where we are re-writing functions the others have written or using a timer module that someone else is using for something else.

What is best practice for documenting embedded C?

Best Answer

As already pointed out by others, an architecture can help to tackle this problem.

Is your implementation a bare metal implementation or do you have an operating system? Sorry, I couldn't ask in the comments, because my reputation level is too low. If it is a bare metal implementation I made good experiences with following layering for small(ish) to mid-sized projects:

  • Application layer: this is where your business logic goes
  • Device layer: device driver
  • Hardware Abstraction layer (HAL): The only layer that accesses the hardware
  • Base: Contains utility functions
  • System: Contains the scheduler, event system, logging etc.

The calling direction would be:

  • Application > Device > HAL
  • Every layer can all into Base and System

It is also very important to modularise your system and define how the modules communicate with each other (ideally over an event system)

Related Topic