0

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?

Improve this question
5
  • 2
    The best practice is to write the documentation in such a way that it is as clear as possible to the developer coming after you. Also, the best possible practice is to make sure your code is as clear as possible so that the documentation required is minimal.
    – Robert Harvey
    Dec 23, 2016 at 15:33
  • We do follow that. There is not a single function that anyone of us has written that is not very clear. However that doesn't prevent us from stepping on each others toes.
    – Reid
    Dec 23, 2016 at 15:37
  • 10
    It sounds like you lack an architectural design. Projects with an architectural design avoid duplication of effort, because everyone can see that there is already a timer module in the architecture.
    – Robert Harvey
    Dec 23, 2016 at 15:40
  • 3
    You don't have a documentation problem, you have a communication problem. Either it isn't being made known that functions of general use are being added or they aren't being added someplace common like a utility library where people would know to look for them before writing their own.
    – Blrfl
    Dec 24, 2016 at 14:53
  • Yes, Blrfl is right, you are asking the very, very wrong question. You do not need more or better documentation. You need to organize your workplace communication better, teach modularity among your team (and make use of it), teach basics about writing code in a more self-documenting manner, and so on. This is mainly a management issue. Unfortunately, your problems cannot be solved by one short answer here on this site, this is way too broad. Oh, and it is also a misconception that this has anything to do with embedded C.
    – Doc Brown
    Dec 25, 2016 at 7:29

2 Answers 2

Reset to default
5

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)

Improve this answer
0

I don't know that there is such a thing.

However, since you are writing in C, you need to explicitly encourage discipline around modularity. I would urge you to have a lightweight architecture that is composed of layers of abstractions, probably 2 or three layers to start. Each layer exposes concepts, behaviors, and relationships to a useful completeness that the next consuming layer can use without having to reach around to the next lower layer or bare metal.

Within a layer you can have additional modularity, akin to classes in other languages.

I'd then document the layers and how they are arranged relative to each other, next the layer interfaces. And then within a layer, the organization therein.

When you have that lightweight architecture, you'll have a clearer notion of where things should live, and hopefully a better idea of where to look for already existing abstraction and capabilities.

With a lightweight architecture, you'll also have names of layers and other modules that facilitates discussion and speeds communication with your colleagues.

Improve this answer
2
  • 4
    This is really abstract without an example. Layered architecture is mostly associated with line of business applications, and unfortunately the OP hasn't said much about his application other than it is written in C and has hundreds of functions.
    – Robert Harvey
    Dec 23, 2016 at 15:54
  • @RobertHarvey, I take your point. Still, when I write in C or even JavaScript, if I'm writing more than a few hundred lines of code, I try to create modularity through layers. I'm not trying to suggest some web application architecture, though!
    – Erik Eidt
    Dec 23, 2016 at 15:59

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.