Quellcode in der Projektdokumentation

[kirin]

Hallo,

naja, was soll ich sagen: Ich bin halt neu hier und hab ne Frage....

Ich bin FiSI und entwickel als Projektarbeit eine PHP-Anwendung für unsere Benutzer. Nun bin ich schon gut weit in der Dokumentation, hab diese ordentlich gegliedert und überlege momentan eigentlich nur, wie ich die PHP-Programmteile darstelle.

Sollte ich:

1. Eine kurze Beschreibung des Quellcodes/ der Funktion in der eigentlichen Dokumentation schreiben und den Quellcode und oder Struktugramm in den Anhang packen?

2. Eine kurze Einleitung in die Funktion des folgenden Programmteils mit einem Struktogramm in die Doku und den Quellcode in den Anhang schieben?

oder 3. Den Quellcode in die Doku pasten, und dort nur mit den Kommentaren aus dem Quellcode arbeiten?

gibt es vielleicht noch eine bessere Alternative?

Gruesse

Kirin

[baba007]

Bei uns ist das so, dass kein Quellcode in die Doku kommt. Auch in der technischen Doku ist das kein Bestandteil.

[CSC]

Wenn überhaupt, dann 2.

Ich habe damals auch keinen Code in meine Dokus gepastet. Das ist auch wenig sinnvoll. Mit einem Struktogramm kann man die wesentlichen Zusammenhänge besser erklären als mit (wirren) Programmcode. Man muss auch bedenken, dass nicht alle Prüfer programmieren können

[perdian]

Ich habe damals auch keinen Code in meine Dokus gepastet.

Ich auch nicht, und würde auch immer sagen "lass es". Das Programmieren selbst ist "nur" das Werkzeug, mit dem das Ziel (das Projekt) erreicht wird. Und nirgendwo sonst wird das Werkzeug mit in eine Dokumentation übernommen. Ein Elektriker wird auch nirgendwo Kabel oder den Schraubendreher, mit dem er gearbeitet hat, mit in eine Dokumentation einfügen. Selbst über ein Struktogramm lässt sich streiten - sobald es hier über ein paar sehr einfache Befehle hinausgeht wird sowas nämlich auch sehr schnell sehr unübersichtlich. Ich habe (als AE) damals ein Diagramm zusammengestellt, in dem grob der Ablauf der Applikation dargestellt ist, ohne mich dabei an irgendwelche formalen PAP oder Flussdiagramm Regeln zu halten.

Es geht schließlich darum fundiert zu belegen, wie man sein Projekt erledigt hat und nicht darum zu beweisen wie tollen Code man schreiben kann.

[siamskij_kot]

Du bist FISI und darfst in deiner Projektarbeit programmieren?

Beschränkt die Projektarbeit sich nur auf die Programmierung, oder ist es nur ein Teil vom Ganzen?

[kirin]

Das is Teil eines Ganzens. Ich erstelle eine Webanwendung, mit der die Benutzer ihre Daten wie Telefonnummer, E-Mail-Adresse in unserem AD speichern können.

Hab jetzt so gemacht, dass ich in der Doku nur die grundlegenden Funktionsweisen geschrieben habe und die benutzen Funktionen als Quellcode mit vielen Kommentaren in den Anhang gepackt.

Gruesse

Kirin

[siamskij_kot]

Das is Teil eines Ganzens. Ich erstelle eine Webanwendung, mit der die Benutzer ihre Daten wie Telefonnummer, E-Mail-Adresse in unserem AD speichern können.

Hab jetzt so gemacht, dass ich in der Doku nur die grundlegenden Funktionsweisen geschrieben habe und die benutzen Funktionen als Quellcode mit vielen Kommentaren in den Anhang gepackt.

Gruesse

Kirin

Oha... und das reicht für ein Abschlussprojekt?

Hätte nicht gedacht,dass so ein einfaches "Ding" für einen FISI ausreichen wird.

[Enelya]

manchmal ist weniger eben mehr