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?

  • 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 '16 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 '16 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 '16 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 '16 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 '16 at 7:29
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)

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.

  • 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 '16 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 '16 at 15:59

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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