How can german language pods be integrated into the main
distribution? I'm currently trying to get a german perl
documentation project going, so this is not just a theoretical
question.
I've already translated the smallest core pod I could find:
perlstyle.pod
Sean's proposal of putting the different language versions into one file
> =for :lang en
> Hooboy, this does something!
>
> =for :lang es
> E<iexcl>Wuju! Hace algo
didn't seem right for stand-alone pods, so I'm currently saving it
as perlstyle.pod.de. What do I do with it now? Where do I hand it in?
And how can I find the original author? I'd like to give him/her a
chance
to check the translation.
bye for now
Brigitte
p.s. I'm also taking this to de.comp.lang.perl.misc,
to discuss the quality of the translation and stuff like that.
-------------------- begin perlstyle.pod.de ----------------------
=head1 NAME
perlstyle - Perl Programmierstil
=head1 DESCRIPTION
Jeder Programmierer, jede Programmiererin hat nat�rlich eigene Vorlieben
wenn es um die Formatierung von Programmen geht, aber es gibt ein
paar allgemeine Regeln um Programme einfacher lesbar, einfacher
verst�ndlich, und einfacher wartbar machen.
Das Wichtigste ist immer die B<-w> Option zu verwenden. In einzelnen
Teilen des Programmes kann man die Wirkung mit dem C<use warnings>
Pragma oder der C<$^W> Variable abschalten, falls das unbedingt n�tig
ist. Sie sollten auch immer C<use strict> verwenden (oder eine
verdammt gute Ausrede haben warum Sie es nicht tun).
Auch C<use sigtrap> und sogar C<use diagnostics> k�nnen hilfreich sein.
Wenns um die �sthetik geht, hat Larry nur eine besondere Vorliebe:
die schliessende Klammer eines mehrzeiligen BLOCKs soll gleich
weit einger�ckt sein wie das Schl�sselwort mit dem die ganze
Konstruktion
anfing. Alles weiter sind blos Empfehlungen:
=over 4
=item *
4 Zeichen breite Einr�ckung.
=item *
�ffnende geschwungene Klammer bleibt m�glichst in der selben Zeile wie
das
Schl�sselwort, oder auf gleicher Einr�ckungs-Tiefe.
=item *
Leerzeichen vor der �ffnenden geschwungenen Klammer eines mehrzeiligen
BLOCKs.
=item *
Einzeiliger BLOCK kann auf eine Zeile geschrieben werden,
inklusive der Klammern.
=item *
Kein Leerzeichen vor dem Semikolon.
=item *
Kein Semikolon in "kurzem", einzeiligem BLOCK.
=item *
Leerzeichen vor und nach den meisten Operatoren.
=item *
Leerzeichen rund um "komplizierte" Indices (innerhalb
der Klammern)
=item *
Leerzeilen zwischen Programm-Abschnitten die verschiedene
Sachen machen.
=item *
else nicht auf einer Zeile mit beiden Klammern.
=item *
Kein Leerzeichen zwischen Funktionsname und
dazugeh�render �ffnender Klammer.
=item *
Leerzeichen nach jedem Komma.
=item *
Lange Zeilen nach dem Operator umbrechen,
Ausnahmen sind "and" und "or".
=item *
Leerzeichen nach der letzten schliessenden Klammer,
die auf der aktuellen Zeile ge�ffnet wurde.
=item *
Zusammengeh�rende Sachen vertikal gleich ausrichten.
=item *
Redundante Zeichen weglassen, solang das Programm
verst�ndlich bleibt.
=back
Larry hat seine Gr�nde f�r all diese W�nsche,
aber er behauptet nicht, dass Sie das auch so sehen
m�ssen.
Hier sind noch ein paar wichtige Stilfragen, �ber die
man mal nachdenken sollte:
=over 4
=item *
Nur weil man etwas auf eine bestimmte Art schreiben
I<KANN>, heisst das nicht, dass man es auch I<SOLL>.
In Perl gibts immer eine Vielzahl an Schreibweisen,
versuchen Sie es doch mal mit der vern�nftigsten.
zum Beispiel:
open(FOO,$foo) || die "Kann $foo nicht �ffnen: $!";
ist besser als
die "Kann $foo nicht �ffnen: $!" unless open(FOO,$foo);
weil bei der zweiten Schreibweise das Wichtigste
erst ganz zum Schluss kommt. Auf der anderen Seite:
print "Beginne mit der Analyse\n" if $meldungen;
ist besser als
$meldungen && print "Beginne mit der Analyse\n";
weil die Pointe in der Ausgabe liegt, nicht im Flag.
Nur weil ein Operator mit der Standardvariablen arbeitet
heisst das noch nicht, dass man diese M�glichkeit verwenden
muss. Diese Standard-Einstellungen sind f�r faule Leute
die Wegwerf-Programme schreiben. Wenns lesbar
sein soll, sollte man vielleicht die Argumente auch
hinschreiben.
Ein �hnliches Thema sind Klammern: blos weil ich sie
weglassen I<KANN>, heisst das nicht das ich folgendes
schreiben soll:
return print reverse sort num values %array;
return print(reverse(sort num (values(%array))));
Im Zweilfelsfall klammern. Dann kann irgend ein armer
Schlucker wenigstens mit der %-Taste im vi zwischen
den Klammern rumh�pfen.
Denken Sie immer auch an den geistige Gesundheit des armen
Menschen, der Ihren Code warten muss (und wahrscheinlich
flasche Klammern einf�gen wird).
=item *
Machen Sie sich nicht viel Umst�nde um aus einer Schleife
brav am Ende auszusteigen; Perl bietet den netten
C<last> Befehl um in der Mitte auszusteigen. Die C<last>-Zeile
k�nnen Sie ein bisschen "ausr�cken", damit sie mehr hervorsticht:
EUMEL:
for (;;) {
befehle;
last EUMEL if $foo;
next EUMEL if /^#/;
befehle;
}
=item *
Keine Angst vor Schleifen-Namen. Schleifen-Namen sind gut.
Sie erh�hen die Lesbarkeit, und man kann damit (sicher)
aus vernesteten Schleifen aussteigen. Siehe voriges
Beispiel.
=item *
Vermeiden sie C<grep()> (oder C<map()> oder C<`backticks`>)
in einem Void-Kontext, d.h. wenn der R�ckgabewert nicht
benutzt wird. Wenn Sie den R�ckgabewert nicht brauchen
sollten Sie eine C<foreach()>-Schleife oder die
C<foreach()>-Funktion verwenden.
=item *
Denken Sie an die Portierbarkeit. Falls Sie etwas verwenden,
was auf anderen Plattformen vielleicht nicht funktioniert,
testen sie die Konstruktion in einem C<eval> um rauszufinden
ob es funktioniert. Falls Sie genau wissen unter welcher
Perl-Version oder bei welchem Patch-Level das Feature funktioniert
k�nnen Sie auch C<$]> (C<$PERL_VERSION> bei Verwendung
von C<use English>) abfragen. Auch mit dem C<Config> Module
kann man rausfinden was mit B<Configure> eingeschalten wurde,
als Perl kompiliert wurde.
=item *
K�nnen Sie sich noch dran erinnern, dass Sie Variablennamen
verwenden wollten, die man sich leicht merken kann?
Nein? Dann haben Sie ein Problem.
=item *
Ganz kurze Variablennamen wie C<$warda> sind ok, bei l�ngeren
Zusammensetzungen verenden Sie bitte Unterstriche um W�rter zu
trennen. $wenn_man_es_so_schreibt ist es leichter lesbar als
$WennManEsSoSchreibt. Besonders wenn man englische Variablennamen
verwendet: $var_names_like_this ist besser als $VarNamesLikeThis.
Gilt auch $WENN_MAN_ES_SO_SCHREIBT.
Eine Ausnahme von dieser Regel sind Namen von Packages. Da sind
die klein geschriebenen Namen f�r "pragma"s reserviert (wie C<integer>
und C<strict>). Alle anderen Module sollten mit Grossbuchstaben
beginnen, und keine Unterstriche enthalten. (Aus R�cksicht auf
Betreibssysteme mit Beschr�nkungen bei Dateinamen-L�ngen.)
=item *
Es kann hilfreich sein, wenn man die Gross-/Kleinschreibung
n�tzt, um den Wirkungsbereich einer Variable anzudeuten. z.B.:
$ALLES_GROSS nur Konstanten (eventuell Konflikt mit eingebauten
Perl Variablen!)
$Manches_Gross Globale/Statische Variablen
$ganz_klein lokale Variablen in einer C<sub>, mit C<my> oder
C<local>
Funktionen und Methoden schreibt man am besten ganz klein:
E.g., $objekt-E<gt>als_text().
Mit einem Unterstrich als erstes Zeichen k�nnen Sie andeuten,
dass eine Variable oder Funktion "privat" ist,
also nicht von ausserhalb des Module aus benutzt werden soll.
=item *
Bei ganz komplizierten regul�ren Ausdr�cken: verwenden
Sie den Modifikator C</x> und Whitespace, damit das
ganz nicht gar so nach "Der Fluch des Asterix" aussieht.
Falls im Muster Schr�gstriche vorkommen, dann verwenden
Sei ein B<anderes> Zeichen als Begrenzung des Musters.
=item *
Benutzen Sie C<and> und C<or> dort wo es Klammern spart
statt C<&&> und C<||>. Lassen Sie das kaufm�nnische Und
vor Aufrufen von C<sub>s weg.
=item *
Verwenden sie Hier-Dokumente statt ewiger C<print>s.
=item *
Bringen Sie Sachen vertikal auf Linie.
$IDX = $ST_MTIME;
$IDX = $ST_ATIME if $opt_u;
$IDX = $ST_CTIME if $opt_c;
$IDX = $ST_SIZE if $opt_s;
mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
chdir($tmpdir) or die "can't chdir $tmpdir: $!";
mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
=item *
Beachten Sie immer den R�ckgabewert von Betriebssystem-Aufrufen.
Schreiben Sie gute Fehlermeldungen auf STDERR, mit
Programmname, was schiefgegangen ist, und B<ganz wichtig>
der Fehlermeldung vom System C<$!>.
Ein einfaches, aber hinreichendes Beispiel:
opendir(D, $dir) or die "$0: Kann Ordner $dir nicht lesen: $!";
=item *
Zeichenersetzungen mit C<tr> untereinander ausrichten:
tr [abc]
[xyz];
=item *
Denken Sie �ber Wiederverwendbarkeit nach. Warum Hirnschmalz an
ein Wegwerf-Programm verschwenden, wenn mans vielleicht nochmal
brauchen k�nnte? Geht's vielleicht ein bisschen allgemeiner?
Sollte es vielleicht ein Modul oder eine Klasse sein?
Sollte es doch vielleicht auch mit C<use strict> und C<use warnings>
(oder B<-w>) funktionieren? Sollten Sie das Programm vielleicht
herschenken? Sollten Sie Ihre Leben �ndern? Sollten Sie Schokolade
f�r Brigitte spenden .... oops, da hat sich ein �bersetzungsfehler
eingschlichen.
=item *
Sei konsistent.
=item *
Sei freundlich.
=back
---------------------- end perlstyle.pod.de ----------------------
--
Brigitte 'I never met a chocolate I didnt like' Jellinek
[EMAIL PROTECTED] http://www.horus.com/~bjelli/
http://perlwelt.horus.at http://www.perlmonks.org/index.pl?node=bjelli
