develooper Front page | perl.perl5.porters | Postings from July 2001

translation experiment (was: pod in multiple languages?)

From:
Brigitte Jellinek
Date:
July 11, 2001 15:42
Subject:
translation experiment (was: pod in multiple languages?)
Message ID:
3B4C6F82.CADFB648@horus.at
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
bjelli@horus.com                         http://www.horus.com/~bjelli/
http://perlwelt.horus.at http://www.perlmonks.org/index.pl?node=bjelli



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About