C-Software-Dokumentation

[Siro]

Bitte erschlagt mich nicht wegen diesem Thema:

Ich mache mir grad einen Kopf darüber wie ich meine Software dokumentieren bzw. archivieren soll. Da dies zu jedem C-Programm gehört (bzw. sollte), denke ich mal, es gehört auch in dieses Forum.

Ich habe davon ehrlich gesagt gar keine Ahnung. Laut Firma sind wir zertifiziert nach :
EN ISO9001:2000, EN ISO 13485:2003+AC:2007 Anhang II
Was immer das bedeuten mag, weis ich nur, es geht um Medizintechnik.
Wo finde ich Dokumentation, wie ich meine Software entsprechend dokumentieren, verifiziern, validieren und archivieren muss ?
Okay, das sind jetzt 4 Fragen auf einmal, aber vielleicht hat jemand einen oder einige LINKs zu diesem Thema. Vielleicht auch eine Buchempfehlung.

Wo liegt Beispielsweise mein Problem ?

Ich benutze z.B die Datei: <string.h> Wenn man sich diese ansieht, benötigt sie, bei meinem IAR-Compiler, zusätzlich folgende Dateien:
#include <ycheck.h>
#include <yvals.h>
#include <ysizet.h>

Das sind jedoch Dateien, welche in meinem eigentlichen Projekt garnicht auftauchen, dementsprechend sich auch nicht in meinem Projektverzeichnis befinden.
Sie schwirren, je nach Installation, irgendwo auf einer Platte vielleicht auch auf einem Server rum, wenn ich das so ausdrücken darf.
Meiner Meinung nach müste ich diese Dateien direkt in mein Projektverzeichnis kopieren und dann mit "" includen anstelle von <> denn nur so kann ich sicherstellen, daß der Compiler auch die Dateien aus meinem Verzeichnis benutzt.
Wenn ich dies nicht mache, könnte ein neues Update des Compilers diese Dateien geändert haben, was später zu einem anderen Compilat führen wird. Die Nachvollziehbarkeit meiner Software ist damit nicht mehr gegeben. Eigentlich muss ich meinen kompletten Compiler bzw. IDE mit dem Projekt zusammen ablegen um später auf identischen Code zu kommen. Da ich nicht die geringste Ahnung von dieser Materie habe, wäre ich für Informationen sehr dankbar, oder habe ich vielleicht eine Rubrik in diesem Forum übersehen ?

Fürchterliches Thema, ich weis......
Siro

Zusatz: ja, ich habe schon gegoogelt aber nix über Software-Doku gefunden
aber vielleicht habt Ihr etwas Info zu dem beschriebenem Problem der Dateien. Danke Euch

[ePyx]

Also bisher hatte ich meine Software-Doku immer mit Doxygen gemacht.

[oberallgeier]

... Laut Firma sind wir zertifiziert nach : EN ISO9001 ...

Diese Zertifizierung nach Odyssee-9001 beschäftigt sich mit der so genannten Qualitätssicherung, sprich (quick+dy) mit der Nachverfolgbarkeit der Dokumente. Das hat mit Qualität so viel zu tun, wie der Watson mit der Spürnase von Sherlock Holmes. Garnix. Es werden damit nur Richtlinien bzw. Vorschriften bereitgestellt, was alles dokumentiert werden muss, damit man später feststellen kann, wer wann welchen Murks gemacht hat.

... Wo finde ich Dokumentation ...

Das sollte in Deinem QS-Handbuch zu finden sein. Allerdings wirst Du vermutlich kein fertiges Rezept mit Angabe der Organisationshilfen finden, es sei denn, Ihr produziert nicht unwesentlich Software und irgendjemand hat das auch gepeilt und sich darum gekümmert. Ich glaub das nicht (ohne DEINEN Betrieb zu kennen).

... könnte ein neues Update des Compilers diese Dateien geändert haben ...

Wie wahr. Auch Deine nachfolgenden Schlüsse . . . .

In großen Projekten mit absoluter Verfolgbarkeit wird auch regelmässig (bis zu 1xnächtlich) ein Backup geDVDt und dafür gesorgt, dass alle Beteiligten bei der aktuellen Tagesarbeit NUR auf die aktuellen und gleichen Dateien Zugriff haben. Es gibt also zwei Themenkreise: 1. die Dokumentation und Sicherung des aktuellen Werkzeugbestandes (Compiler, libs, eigene Quellen bis hin zu handschriftlichen Notizen, Dok der aktuellen Hardware) und 2. die Dokumentation des Softwareaufbaues (Ablaufpläne uä, Listings). Beides jeweils mit Versionsnummer und Datum gekennzeichnet. Damit kannst Du dann bei (Beispiel) der Anfrage aus den Tiefen von Mütterchen Russland, viele Monate nach Auslieferung, nach einem eher singulären Problem in der gelieferten Software relativ schnell den Grund finden, beheben und die geänderte Softwre liefern - und die läuft dann auch.

[Siro]

zu ePyx:
Das Doxygen habe ich mir schon heruntergeladen, nur noch nicht ausprobiert. Wenn ich das recht verstanden habe, wird hier im Source Code über spezielle Ascii Sequenzen später ein automatisches Dokument erstellt. Ob das so eingesetzt werden darf in meinem Fall, weis ich leider nicht. Ich danke Dir aber für die Info.

zu oberallgeier:
Deiner Anwort nach, entnehme ich, daß Du mit dieser Materie recht gut vertraut bist. Das Thema Software scheint also ein recht komplexes Thema zu sein,
Es stellt sich mir grade die Frage, ob wir überhaupt eine Softwaredokumentation benötigen. Wir vertreiben ja keine Software in dem Sinne, sondern medizintechnische Geräte. Diese könnten intern theoretisch auch nur mittels Hardware aufgebaut sein. Also brauche ich doch nur eine "Abnahme" für das Gerät als "ganzes" oder sehe ich das falsch ? Wie ich es intern gelöst habe, dürfte doch dann unerheblich sein, solange ich Sicherstellen kann, daß durch einen Fehler im Gerät der Patient keinen Schaden nehmen kann. Bleibt also zunächst die Frage, wann muss ich Software dokumentieren, oder muss ich das generell wenn ich einen Prozessor (Controller) im Gerät verwende.
Danke auch Dir für Deine Info.
Siro

[oberallgeier]

... Deiner Anwort ... entnehme ich, daß Du mit dieser Materie recht gut vertraut bist ...

Jein. Ich habe aber an (m)einem Teil des QS-Handbuches manches mitgeschrieben. Und mich über vielerlei Ignoranz so mancher Zertifizierungsgesellschaft geärgert - und über manche hochgradig kompetente Zertifizierer gefreut.

... Frage, ob wir überhaupt eine Softwaredokumentation benötigen. Wir vertreiben ja keine Software in dem Sinne, sondern medizintechnische Geräte ...

Was sagt denn der QS-Beauftrage (Achtung, keine schlafenden Hunde wecken)? Das ist de jure meist der Geschäftsführer, der die Arbeit aber üblicherweise deligiert an einen Fachmann (das könnte im schlimmsten Fall ein Kaufmann sein - der hat mit SW vielleicht gar nix am Hut).

... medizintechnische Geräte ... könnten intern theoretisch auch nur mittels Hardware aufgebaut sein ...

Aha - und für Hardware braucht man ja keinen Plan, keine Spezifikation, keine Liefernachweise, keine Funktionsbeschreibung, keinen Funktionsnachweis, garnix. Kommt mir irgendwie bekannt vor. Aber - Software braucht man dafür natürlich nicht. Störend ist bei Deiner Überlegung nur das "könnte". Meist wird die Dokumentation verlangt "as build", zumindest von den Kunden/Zertifizierern die wissen wie der Hase läuft. Egal was könnte . . . .

... Wir vertreiben ja keine Software in dem Sinne, sondern medizintechnische Geräte ...

Für Deine Entscheidungsfindung oder die Deines QS-Vormannes könnte ein bisschen Stöbern in den Cyber Letters der FDA helfen. Die Cyber Letters sind the (US-) american way of Mittelalter-Pranger. Lies es aber bitte NUR im Sitzen. Mit Arm- und Rückenlehne. Vielleicht ein Glas Wasser neben Dir.

... also zunächst die Frage, wann muss ich Software dokumentieren, oder muss ich das generell wenn ich einen Prozessor (Controller) im Gerät verwende ...

M.E. generell - wenn Prozessor. BTW: lies Dir die Ausschlussfloskel für Medizingeräteanwendungen in den Atmel-Docs durch. Oder in den Docs die Du einsetzt. Wieder: nur im Sitzen.

Viel Erfolg

[markusj]

zu ePyx:
Das Doxygen habe ich mir schon heruntergeladen, nur noch nicht ausprobiert. Wenn ich das recht verstanden habe, wird hier im Source Code über spezielle Ascii Sequenzen später ein automatisches Dokument erstellt.

Hallo Siro,

um genau zu sein sind es einfach nur Kommentare im Quelltext, die mit einem zusätzlichen Stern erweitert wurden damit Doxygen diese von "normalen" Kommentaren unterscheiden kann.

/* normaler Kommentar */
/** Doxygen Doku */

Damit hat die Dokumentation keinen Einfluss auf die Funktionalität Quellcodes.

mfG
Markus

[Siro]

Danke Markus,
hab mir grad mal ein Tutorial von Doxygen angesehen. Das sieht recht simpel aus.

Dein Satz: "Damit hat die Dokumentation keinen Einfluss auf die Funktionalität des Quellcodes"
find ich gut, weil ebensowenig hat die ISO Einfluss auf die Qualität des Gerätes Irgendwer hier im Forum hat mal gesagt , "Pfuschen" erlaubt, solange es dokumentiert wird.

Siro

[ePyx]

Also ich benutze Doxygen eigentlich für fast alles. Egal ob es Source für Uni, Arbeit oder privat ist, wird alles so gut es geht in den kommentaren dokumentiert.

Damit hat die Dokumentation keinen Einfluss auf die Funktionalität Quellcodes.

In dem Punkt stimmt die Aussage in sofern, dass man kein Extraprogramm benötigt, was man "nebenbei" noch bewältigen und pflegen muss.

Mittels Doxygen kann man recht simpel HTMl, CHM-Files oder PDFs erzeugen und mit den richtigen Tools (GraphWiz usw.) Werden Include- und Aufrufgraphen sowie Klassendiagramme automatisch erzeugt.

Das Prinzip von Doxygen, also die Erstellung von Kommentaren ist in sofern hilfreich:
1. da Doku und Source den gleichen Inhalt hat
2. man nur an einer Front kämpft
3. und man angehalten wird den Quelltext selbst mit sinnigen Komentaren zu versehen