Wohin mit Kommentaren und Namenskonventionen

[kai-carsten]

Hallo!

Ich beginne bald mein erstes großes Projekt mit VB.NET.

Es geht um allgemeine Kommentare, die das gesamte Programm betreffen und Dinge wie Namenskonventionen usw.: Wo bringt man diese in einem größeren Projekt am besten unter?

Gruß

Kai

[Ralf Jansen]

Wo bringt man diese in einem größeren Projekt am besten unter?

Da gibt es keinen typisch richtigen Ort. Was ich bisher am günstigsten empfand war ein Wiki. Man kann dann wunderbar aus den Kommentaren im Sourcecode in die entsprechenden Wiki Artikel verlinken um dort weiter zu lesen. Ein Wiki (wahrscheinlich durch seine unstrukturierte Art) hat scheinbar auch psychologische Vorteile bei Entwicklern. Die werden eher synchron zur Wirklichkeit im SourceCode gehalten als sonstige Dokumente in irgendwelchen (dann durchdesignten und mit Corporate-Identity-Geschichten voll gestopften) Officeformaten.

[Bernhard Geyer]

Wie wäre es mit einem Projekthandbuch?

[kai-carsten]

Danke Euch beiden, aber ich dachte eher an eine Nummer kleiner, irgendwo beim Code. Gibt es da einen typischen Ort für "Allgemeines"?

[Bernhard Geyer]

Bevor du das Codieren anfängst ist sowas schon festgelegt. Und dort ist das Projekthandbuch (evtl. in WIKI-Form) zu verwenden.

Sowas wie Namenskonventionen, Begriffsdefinitionen betrifft ja nicht nur die Mitarbeiter die mit Quellcode zu tun haben sondern auch die Mitarbeiter die Handbücher oder Onlinehilfe schreiben oder das fertige Produkt im Intra/Internet vorstellen. Auch das Marketing will evtl. mal "Reinschauen".

[fanderlf]

Was sind denn allgemeine Kommentare?

Für Namenskonventionen würde ich Dir ein Tool empfehlen. Am Besten so etwas wie ReSharper oder CodeRush. Dort werden Namen die nicht den Namenskonventionen entsprechen direkt markiert.

[kai-carsten]

Sorry, vielleicht hätte ich erwähnen sollen, dass ich Auftraggeber, Auftragnehmer, Entwickler und Marketingabteilung in Einem bin :-)

Ein Projekthandbuch oder Ähnliches existiert nicht.

[Ralf Jansen]

In dem Fall wähle das was dir am besten liegt.

Im simpelsten Fall packe einfach eine Textdatei mit in die Solution und schreib rein was du für Dokumentationswürdig hältst aber nicht direkt in den SourceCode schreiben willst.

Nur für sich selber eine Namenskonvention zu schreiben und irgendwo abzulegen ist aber schon ein wenig strange oder

[fanderlf]

Ich finde es schadet aber auch gar nicht wenn man für sich selbst ein Pflichtenheft u.ä. schreibt. Manchmal verliert man beim Programmieren einfach den Fokus und verrennt sich in Sachen die gar nicht wichtig sind. Hin und wieder ein Blick ins Pflichtenheft öffnet einem die Augen und zeigt wo man eigentlich hin will

[kai-carsten]

Nur für sich selber eine Namenskonvention zu schreiben und irgendwo abzulegen ist aber schon ein wenig strange oder

Naja, ich will mir die Option offenhalten, das Projekt evtl. mal weiterzugeben.

[kai-carsten]

Ich finde es schadet aber auch gar nicht wenn man für sich selbst ein Pflichtenheft u.ä. schreibt. Manchmal verliert man beim Programmieren einfach den Fokus und verrennt sich in Sachen die gar nicht wichtig sind. Hin und wieder ein Blick ins Pflichtenheft öffnet einem die Augen und zeigt wo man eigentlich hin will

Naja, ich code nach einer einfache Projektplanung in Excel...

[2char]

Die IDE bietet die Möglichkeit functionen subs usw. deren funktionalität parameter und rückgabewerte zu beschreiben.

Einfach eine Zeile über der function/sub... drei mal das ' (hochkomma) tippen.

VB fügt darauf hin
den entsprechenden XML kommentar ein:

''' <summary>
'''
''' </summary>
''' <remarks></remarks>

dieser kommentare werden dann wiederum im intellisense angezeigt!


Gruß
2char