seeseekey.net - Invictus Deus Ex Machina

Ein Quelltext wird während der Entwicklung gewöhnlich kommentiert. Unter C# bzw. .NET gibt es dafür Kommentare nach einem bestimmen Schema. Über einer Methode könnte ein solcher Kommentar z.B. aussehen:

/// <summary>
/// Distance between a and b.
/// </summary>
/// <param name="a">The first vector.</param>
/// <param name="b">The second vector.</param>

Diese Kommentare kann die freie Software Doxygen auswerten und daraus eine Dokumentation erzeugen. Im Gegensatz zu anderen Lösungen wie Sandcastle ist Doxygen betriebsystemübergreifend verfügbar und kann somit — wie in diesem Beispiel — unter Mac OS X genutzt werden. Im ersten Schritt sollte Doxygen installiert werden. Unter Mac OS X kann dies einfach über MacPorts geschehen:

sudo port install doxygen

Nachdem Doxygen installiert ist, sucht man im Terminal den Ordner des Entwicklungsprojektes heraus und gibt dort ein:

doxygen -g projektname.doxygen

Damit wird eine Standard-Doxygen-Konfiguration erzeugt. In dieser Datei werden nun ein paar Änderungen vorgenommen:

PROJECT_NAME = "Testprojekt"
PROJECT_NUMBER = "Release Candidate 1"
OUTPUT_DIRECTORY = docs
RECURSIVE  = YES

Über den Aufruf:

doxygen projektname.doxygen

kann nun die HTML-Dokumentation des Quelltextes erzeugt erzeugt werden und diese anschließend im Browser genutzt werden.

Bücher über PHP-Entwicklung gibt es wie Sand am Mehr. Bücher an denen man mitarbeiten kann allerdings weniger. Zu dieser Klasse von Büchern gehört PHP — The Right Way, deren Quelltext auf GitHub zu finden ist. In dem Buch geht es dabei nicht nur um die Sprache PHP als solches, sondern auch um die Entwicklungsumgebung, Sicherheit und andere Themen.

Die deutsche Version von PHP — The Right Way.

Neben der englischen Originalversion gibt es auch eine ganze Reihe von Übersetzungen. Während es sich bei den Versionen bis zum 10. Juli 2012 noch um eine freie Version unter MIT-Lizenz handelte, wird mittlerweile die deutliche restriktivere Creative Commons Lizenz BY-NC-SA genutzt. Diese schließt eine kommerzielle Nutzung aus. Die offizielle Seite ist unter phptherightway.com zu finden.

Bei meiner Arbeit kommt es öfter mal vor das ich Dateiformat XY implementiere. Dabei gibt es dann unterschiedliche Fälle. Der erste Fall ist das Dateiformat gut dokumentiert ist, und es eventuell sogar schon eine freie Bibliothek für das Format in der passenden Programmiersprache gibt. Dieser Fall ist subjektiv leider der seltenste Fall.

Viel häufiger kommt es vor das das Dateiformat gar nicht, bzw. nur lückenhaft dokumentiert ist. Das liegt manchmal daran das der Hersteller es nicht gerne sieht wenn das Format dokumentiert ist, manchmal auch daran das das Format mit der Zeit organisch gewachsen ist. So sitzt man nun als Entwicker da und fängt an die Formate auseinander zunehmen. So schreibt z.B. Photoshop invalide BMP Header und es kostet viel Mühe so etwas herauszufinden. Nach Stunden, manchmal auch erst Tagen hat man dann endlich das entsprechende Format unterstützt.

Und manchmal frage ich mich dabei, ob es anderen Entwicklern genauso geht und überlege wie viel Arbeit man sich ersparen könnte wenn man eine zentrale Anlaufstelle schafft, in welcher Dateiformate (vorzugsweise in deutscher Sprache) dokumentiert werden. Ich stelle mir da ein Wiki unter einer entsprechenden Lizenz vor (z.B. eine CC-BY) und in diesem werden dann die Dateiformate dokumentiert so das zukünftige Entwickler nicht mehr ganz so viel Arbeit haben. Was haltet ihr von einer solchen Idee?

Immer wieder sieht man es dass man Mails von der Adresse „noreply@noreply.com“ bekommt oder in irgendwelchen Dokumentationen Adressen nach dem Schema „irgendwer@irgendwo.com“ oder „keine@vorhanden.de“ aufgeführt sind. Das Problem an solchen Angaben ist, das sie sehr schlechte Beispiele sind. Wenn ich z.B. als Firma meine Bestellbestätigungen mit „noreply@noreply.com“ als Absender abschicke und der Kunde doch antworten sollte, so hat der Eigentümer der Domain „noreply.com“ plötzlich ein paar sehr interessante Informationen bekommen.

Gegen Dinge wie „noreply@seeseekey.net“ ist nicht einzuwenden, so lange man Eigentümer der Domain ist. Wenn man das ganze nur als Beispiel oder zur Veranschaulichung dient so sollte man eine dieser Domains benutzen:

  • example.com
  • example.net
  • example.org
  • example.edu

Diese Domains sind durch die RFC 2606 als Beispieldomains reservieren und man kann sich auch darauf verlassen, das dies auch in der Zukunft so bleibt.

Weitere Informationen gibt es unter:
http://de.wikipedia.org/wiki/Example.com

TYPO3 ist ein CMS welches man auf den ersten Blick nicht wirklich versteht, zu mindestens ist dies mein Standpunkt. Damit das nicht so bleibt hilft es sich einige Dokumentation durchzulesen bzw. anzuschauen. Eine seht schöne schriftliche Dokumentation gibt es vom Provider Mittwald, welche unter http://www.mittwald.de/typo3-dokumentation/ zu finden ist.

Ist man eher der visuelle Typ so kann man sich den TYPO3 Kurs von Wolfgang Wagner unter http://wowa-webdesign.de/typo3-kurs/ anschauen welcher mittlerweile 74 Folgen umfasst. Dort wird im übrigen gerade nach Themen für neue Folgen gesucht.

Bei der Bashprogrammierung suche ich öfters mal nach einer passenden Zusammenfassung, da ich mir die ganze Syntax nicht merken kann. Fündig geworden bin ich schließlich unter http://de.wikibooks.org/wiki/Linux-Kompendium:_Shellprogrammierung. Dort findet man eine schöne Übersicht aller Befehle und Syntaxkonstrukte. Das wird dann gleich mal in den Lesezeichen verewigt :)

Weitere Informationen gibt es unter:
http://de.wikipedia.org/wiki/Bourne-again_shell