Ein weiteres Leid...
Zu Anfang begann ich Spezifikationen/Systementwürfe in Word95/97 zu schreiben, die viele Entwickler nicht kümmerten und keiner las. Heute sind wir im Jahre 2011 und ich schreibe immer noch technische Dokumentation in Word 2003/2010. Diese Art der Niederschrift technisch, fachlicher Inhalte hat meist ein Problem, dass sie mit sinkendem Abstraktionsgrad sehr stark der eigentlichen Umsetzung hinterherhinkt.
In openwms.org begann ich zu Anfang meine Doku mit OpenOffice Document Format zu schreiben, was sicherlich Word gleichberechtigt ist, allerdings war das eigentliche Problem damit nicht gelöst, da diese Doku immer noch zu weit weg vom eigentlichen Code.
Daher hab ich mir angesehen wie die Spring/JBoss Community ihre Doku schreibt und war davon direkt überzeugt.
Die Dokumentation von openwms.org wird ausschliesslich in DocBook Format geschrieben, passend zum aktuellem Release der Software und generiert durch die Zuhilfenahme von Apache Maven. Als nettes Feature wird sie natürlich in den gewohnten Formaten HTML/HTML-SINGLE und PDF generiert und ist stets für jede Release Version verfügbar.
Das Ganze mit Maven und DocBook zu bauen war etwas tricky, aber machbar :-)
Wer sich also hinsichtlich technischer Dokumentation frei bewegen kann sollte sich einmal DocBook (aktuell in Version 5) und den super Editor XMLMind ansehen. Und wer dann noch mehr wissen möchte wie man mit Maven das alles zu "Papier" bringt sollte nicht zögern und mich anschreiben...
Dienstag, 15. Februar 2011
Montag, 14. Februar 2011
Immer diese Qual mit der IDE
Was ich seit Jahren immer wieder mit Bedauern feststellen muss ist, dass viele Entwickler sich mit der IDE und deren Konfiguration rumschlagen bevor eine Zeile Code geschrieben werden kann. Aus meiner Erfahrung spreche ich über meine Lieblings Java IDE, die Eclipse Umgebung (die wirklich sehr gut ist).
Es beginnt, wenn Plugins installiert werden müssen und dies nicht in der Standardinstallation sondern in einer partiellen Installation der Plugins erfolgt, danach natürlich auch das Konfigurieren der Plugins usw.
Als ich einst den Task hatte, für diesen Prozess eine "Installationsanweisung in Word" zu schreiben, so in der Form ... Download File from here ... Click "Windows->Preferences" habe ich mich wehement dagegen gewehrt. Zudem habe ich bei openwms.org gesehen, dass es für viele Leute einen echten Aufwand bedeutet Eclipse mit speziellen Plugins zu installieren und zu konfigurieren. Nicht umsonst gibt es die sogenannte "Eclipse Distros" die eben eins zum Ziel haben, ein zielgerichtetes Eclipse auszuliefern, für Spring, php oder andere.
Aber das war ja nur der Anfang :-)
Was mich bei Eclipse immer noch störte, ist die Abhängigkeit des Eclipse Workspace zu der lokalen Installation. Manche Einstellungen (Formatter, Templates) lassen sich problemlos ex-und importieren aber eben nicht alle Workspace Einstellungen, somit bleibt der Workspace immer spezifisch zur Installation.
Nicht so mit der OpenWMS.org IDE. Hierbei handelt es sich um einen IzPack Installer der für die gängigsten Umgebungen verfügbar ist und die Installation eines angepassten Eclipse und dessen Workspace vereinheitlicht vornimmt. Dabei werden beide Produkte für den Entwickler und dessen Environment angepasst.
Der Installer führt durch einige wenige Menüs. Neben den Standard Dialogen gibt es auch ein Formular welches zur Eingabe von Benutzerinformation zwingt, diese wird lediglich in den Code Templates des Workspace verwendet. Die Schritte des Installers sowie die Anpassungen möchte ich nun kurz erklären.
Diese angepassten Code Templates haben zur Folge, dass z.B. das Erstellen einer neuen Klasse immer den File Header hat:
/*
* openwms.org, the Open Warehouse Management System.
*
* This file is part of openwms.org.
*
* openwms.org is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* openwms.org is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software. If not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
/**
* A MyClass.
*
* @author Heiko Scherrer
* @version $Revision: $
* @since 0.1
*/
public class MyClass {
Welcome Screen:
Initial Screen mir einigen Infos über die Version des Installers.
License Screen: Listet alle Lizenzen die akzeptiert werden müssen. Ist nichts anders als bei der manuellen Installation ...
User Input: In diesem Screen wird (SVN-) Benutzername, sowie Vor und Nachname und die Email abgefragt. Diese Informationen werden ausschliesslich dazu verwendet um den Header von neuen Java Typen mit den Author Infos zu füllen (Beispiel siehe oben):
Und zu guter letzt die Auswahl der zu installierenden Packs, sprich Eclipse und/oder Workspace:
Und warum das alles? a) Um den Aufwand der manuellen Installation zu sparen, b) um ein einheitliche Entwicklungsumgebung zu haben, welche nicht nur die Formatter und Codetemplates integriert sondern auch noch anderes:
Umfang:
----------
+ Eclipse Helios SR1, JEE Version
+ für Win32, Win64, Linux32, Linux64, Mac64 (weil ich auf allen entwickele ;-)
Plugins:
----------
Checkstyle, Spring IDE, M2Eclipse, Subclipse/Subversive (je nach Platform), Flex Formatter, AIR Gear Plugin
+ Checkstyle auf Remote Rules: http://openwms2005.sourceforge.net/rules/checkstyle/checkstyle.xml, integrated into develop & built lifecycle
+ Customized view layout (Java, Console, Servers, Tasks, ... )
General/Startup and Shutdown
--------------------------------------
+ Disable Usage Data Collector
+ Disable Subclipse Usage Reporting
+ Disable Spring IDE User Agent Analysis Integration
+ Uncheck "Confirm exit when closing the last window"
Usage Data Collector
-------------------------
+ Disable
General/Editors/Text Editors
------------------------------------
+ Insert (4) Space for tabs
+ Show Line Numbers
+ Spelling: User dictionary: "${workspace_loc}/.metadata/user_dictionary" (own dictionary from glossary!!)
General/Editors/File Associations
-----------------------------------------
+ Change default for .mxml to XML Editor
General/Content Types
----------------------------
+ Choose Text->XML and add "*.mxml"
Team/SVN/Label Decorations
------------------------------------
/Text Decorations:
- Remove Outgoing and Added flag
/Icon Decoration:
- Mark all
XML/XML Files/Editor
-----------------------------
- Line Length: 120
- Ident using spaces: 4
XML/XML Catalog
-----------------------
+ Click Add... and add the Flex3.xsd file to user catalog (for better MXML hacking ;-)
Web/HTML Files/Editor
------------------------------
- Line Length: 120
- Ident using spaces: 4
Web/CSS Files/Editor
---------------------------
- Line Length: 120
- Ident using spaces: 4
Validation
-------------
For Manual and Build only activate:
Classpath, DTD, JPA, WAR, XML Schema, XML
FlexFormatting
-------------------
Main page: Use Spaces
Load flexformatter.properties
Auto Format AS Files on Save
Java/Code Style
-------------------
Import custom Codetemplates
+ Mark "Automatically add comments for new methods and types"
Import custom Code Formatter settings
Java/Editor/Templates
----------------------------
Import custom templates
like:
"ulog" (use logger) is...
if (logger.isDebugEnabled()) {
logger.debug("");
}
fix:
// FIXME [your name] :
todo:
// TODO [your name] :
chk (for code reviews):
// CHECK [your name] :
Developers have to check their own tags only instead of having >100 tags with no author!
... and many more code templates
Java/Editor/Save Action
------------------------------
+ Enable Format source code/Format all lines
+ Organize Imports
Additional Settings:
+ Remove unused imports
+ Add missing @Override annotations
+ Add missing @Deprecated annotations
+ Remove trailing whitespaces in all lines
+ Correct indentation
Add Java/Compiler/Task Tag
------------------------------------
Tag: CHECK (Normal)
Maven
--------
+ Mark download sources and javadoc
+ Open always XML editor
+ Show advanced tabs
AIR GEAR
-------------
+ Set FLEX SDK to : ${FLEX_SDK}
/Format:
+ Choose Tab Policy : Space only, intention 4
Da Maven in Verbindung mit IzPack eingesetzt wird und die verschiedenen Artefakte über Classifiers gebaut werden empfiehlt es sich einige Workspace spezifische Files nach der Installation von IzPack/Maven anpassen zu lassen:
/workspace-targetplatform/.metadata/.plugins/org.eclipse.wst.xml.core/system_catalog.xml:
/workspace-targetplatform/.metadata/.plugins/org.eclipse.wst.xml.core/user_catalog.xml:
/workspace/.metadata/.plugins/org.eclipse.jdt.launching/libraryInfos.xml:
Dadurch werden hardcodierte JAVA_HOME Pfade ersetzt und andere benutzerspezifische Dinge aufgelöst.
Wer also Lust auf einen Download der IDE hat sollte sich nicht scheuen und schnell unter openwms.org als Developer registrieren.....
Wer wissen möchte wie man sowas mit Maven & IzPack automatisiert baut darf mich gerne anschreiben.
openwms.org - TAKE THE LEAD
Es beginnt, wenn Plugins installiert werden müssen und dies nicht in der Standardinstallation sondern in einer partiellen Installation der Plugins erfolgt, danach natürlich auch das Konfigurieren der Plugins usw.
Als ich einst den Task hatte, für diesen Prozess eine "Installationsanweisung in Word" zu schreiben, so in der Form ... Download File from here ... Click "Windows->Preferences" habe ich mich wehement dagegen gewehrt. Zudem habe ich bei openwms.org gesehen, dass es für viele Leute einen echten Aufwand bedeutet Eclipse mit speziellen Plugins zu installieren und zu konfigurieren. Nicht umsonst gibt es die sogenannte "Eclipse Distros" die eben eins zum Ziel haben, ein zielgerichtetes Eclipse auszuliefern, für Spring, php oder andere.
Aber das war ja nur der Anfang :-)
Was mich bei Eclipse immer noch störte, ist die Abhängigkeit des Eclipse Workspace zu der lokalen Installation. Manche Einstellungen (Formatter, Templates) lassen sich problemlos ex-und importieren aber eben nicht alle Workspace Einstellungen, somit bleibt der Workspace immer spezifisch zur Installation.
Nicht so mit der OpenWMS.org IDE. Hierbei handelt es sich um einen IzPack Installer der für die gängigsten Umgebungen verfügbar ist und die Installation eines angepassten Eclipse und dessen Workspace vereinheitlicht vornimmt. Dabei werden beide Produkte für den Entwickler und dessen Environment angepasst.
Der Installer führt durch einige wenige Menüs. Neben den Standard Dialogen gibt es auch ein Formular welches zur Eingabe von Benutzerinformation zwingt, diese wird lediglich in den Code Templates des Workspace verwendet. Die Schritte des Installers sowie die Anpassungen möchte ich nun kurz erklären.
Diese angepassten Code Templates haben zur Folge, dass z.B. das Erstellen einer neuen Klasse immer den File Header hat:
/*
* openwms.org, the Open Warehouse Management System.
*
* This file is part of openwms.org.
*
* openwms.org is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* openwms.org is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software. If not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
/**
* A MyClass.
*
* @author Heiko Scherrer
* @version $Revision: $
* @since 0.1
*/
public class MyClass {
Welcome Screen:
Initial Screen mir einigen Infos über die Version des Installers.License Screen: Listet alle Lizenzen die akzeptiert werden müssen. Ist nichts anders als bei der manuellen Installation ...
User Input: In diesem Screen wird (SVN-) Benutzername, sowie Vor und Nachname und die Email abgefragt. Diese Informationen werden ausschliesslich dazu verwendet um den Header von neuen Java Typen mit den Author Infos zu füllen (Beispiel siehe oben):
Und zu guter letzt die Auswahl der zu installierenden Packs, sprich Eclipse und/oder Workspace:
Und warum das alles? a) Um den Aufwand der manuellen Installation zu sparen, b) um ein einheitliche Entwicklungsumgebung zu haben, welche nicht nur die Formatter und Codetemplates integriert sondern auch noch anderes:
Umfang:
----------
+ Eclipse Helios SR1, JEE Version
+ für Win32, Win64, Linux32, Linux64, Mac64 (weil ich auf allen entwickele ;-)
Plugins:
----------
Checkstyle, Spring IDE, M2Eclipse, Subclipse/Subversive (je nach Platform), Flex Formatter, AIR Gear Plugin
+ Checkstyle auf Remote Rules: http://openwms2005.sourceforge.net/rules/checkstyle/checkstyle.xml, integrated into develop & built lifecycle
+ Customized view layout (Java, Console, Servers, Tasks, ... )
General/Startup and Shutdown
--------------------------------------
+ Disable Usage Data Collector
+ Disable Subclipse Usage Reporting
+ Disable Spring IDE User Agent Analysis Integration
+ Uncheck "Confirm exit when closing the last window"
Usage Data Collector
-------------------------
+ Disable
General/Editors/Text Editors
------------------------------------
+ Insert (4) Space for tabs
+ Show Line Numbers
+ Spelling: User dictionary: "${workspace_loc}/.metadata/user_dictionary" (own dictionary from glossary!!)
General/Editors/File Associations
-----------------------------------------
+ Change default for .mxml to XML Editor
General/Content Types
----------------------------
+ Choose Text->XML and add "*.mxml"
Team/SVN/Label Decorations
------------------------------------
/Text Decorations:
- Remove Outgoing and Added flag
/Icon Decoration:
- Mark all
XML/XML Files/Editor
-----------------------------
- Line Length: 120
- Ident using spaces: 4
XML/XML Catalog
-----------------------
+ Click Add... and add the Flex3.xsd file to user catalog (for better MXML hacking ;-)
Web/HTML Files/Editor
------------------------------
- Line Length: 120
- Ident using spaces: 4
Web/CSS Files/Editor
---------------------------
- Line Length: 120
- Ident using spaces: 4
Validation
-------------
For Manual and Build only activate:
Classpath, DTD, JPA, WAR, XML Schema, XML
FlexFormatting
-------------------
Main page: Use Spaces
Load flexformatter.properties
Auto Format AS Files on Save
Java/Code Style
-------------------
Import custom Codetemplates
+ Mark "Automatically add comments for new methods and types"
Import custom Code Formatter settings
Java/Editor/Templates
----------------------------
Import custom templates
like:
"ulog" (use logger) is...
if (logger.isDebugEnabled()) {
logger.debug("");
}
fix:
// FIXME [your name] :
todo:
// TODO [your name] :
chk (for code reviews):
// CHECK [your name] :
Developers have to check their own tags only instead of having >100 tags with no author!
... and many more code templates
Java/Editor/Save Action
------------------------------
+ Enable Format source code/Format all lines
+ Organize Imports
Additional Settings:
+ Remove unused imports
+ Add missing @Override annotations
+ Add missing @Deprecated annotations
+ Remove trailing whitespaces in all lines
+ Correct indentation
Add Java/Compiler/Task Tag
------------------------------------
Tag: CHECK (Normal)
Maven
--------
+ Mark download sources and javadoc
+ Open always XML editor
+ Show advanced tabs
AIR GEAR
-------------
+ Set FLEX SDK to : ${FLEX_SDK}
/Format:
+ Choose Tab Policy : Space only, intention 4
Da Maven in Verbindung mit IzPack eingesetzt wird und die verschiedenen Artefakte über Classifiers gebaut werden empfiehlt es sich einige Workspace spezifische Files nach der Installation von IzPack/Maven anpassen zu lassen:
/workspace-targetplatform/.metadata/.plugins/org.eclipse.wst.xml.core/system_catalog.xml:
/workspace-targetplatform/.metadata/.plugins/org.eclipse.wst.xml.core/user_catalog.xml:
/workspace/.metadata/.plugins/org.eclipse.jdt.launching/libraryInfos.xml:
Dadurch werden hardcodierte JAVA_HOME Pfade ersetzt und andere benutzerspezifische Dinge aufgelöst.
Wer also Lust auf einen Download der IDE hat sollte sich nicht scheuen und schnell unter openwms.org als Developer registrieren.....
Wer wissen möchte wie man sowas mit Maven & IzPack automatisiert baut darf mich gerne anschreiben.
openwms.org - TAKE THE LEAD
Dienstag, 18. Januar 2011
Introduction on Apache Maven2
Check out this SlideShare Presentation:
Introduction on Apache Maven2
View more presentations from Heiko Scherrer.
Abonnieren
Posts (Atom)