Top 15+ Best Practices zum Schreiben von superlesbarem Code

() translation by (you can also view the original English article)

Code Lesbarkeit ist ein universelles Thema in der Welt der Computerprogrammierung. Es ist eines der ersten Dinge, die wir als Entwickler lernen. Dieser Artikel beschreibt die fünfzehn wichtigsten Best Practices beim Schreiben von lesbarem Code.

1 - Kommentieren und Dokumentation

IDEs (Integrated Development Environment) haben in den letzten Jahren einen langen Weg zurückgelegt. Dadurch wurde der Code nützlicher als je zuvor. Wenn Sie bestimmten Standards in Ihren Kommentaren folgen, können IDEs und andere Tools sie auf verschiedene Arten verwenden.

Betrachten Sie dieses Beispiel:

Die Kommentare, die ich in der Funktionsdefinition hinzugefügt habe, können in der Vorschau angezeigt werden, wenn ich diese Funktion verwende, auch aus anderen Dateien.

Hier ist ein weiteres Beispiel, wo ich eine Funktion von einer Drittanbieter-Bibliothek aufrufen:

In diesen speziellen Beispielen basiert die Art der Kommentierung (oder Dokumentation) auf PHPDoc, und die IDE ist Aptana.

2 - Konsistente Einrückung

Ich nehme an, Sie wissen bereits, dass Sie Ihren Code einrücken sollten. Es ist jedoch auch erwähnenswert, dass es eine gute Idee ist, den Eindruckstil konsistent zu halten.

Es gibt mehr als eine Möglichkeit, Code einzurücken.

Stil 1:


function foo() {
  if ($maybe) {
		do_it_now();
		again();
	} else {
		abort_mission();
	}
	finalize();
}

Stil 2:


function foo()
{
	if ($maybe)
	{
		do_it_now();
		again();
	}
	else
	{
		abort_mission();
	}
	finalize();
}

Stil 3:


function foo()
{	if ($maybe)
	{	do_it_now();
		again();
	}
	else
	{	abort_mission();
	}
	finalize();
}

Ich habe im Stil # 2 programmiert, bin aber kürzlich auf # 1 gewechselt. Aber das ist nur eine Frage der Präferenz. Es gibt keinen "besten" Stil, dem jeder folgen sollte. Eigentlich ist der beste Stil ein konsistenter Stil. Wenn Sie Teil eines Teams sind oder Code zu einem Projekt beitragen, sollten Sie dem vorhandenen Stil folgen, der in diesem Projekt verwendet wird.

Die Einrückstile unterscheiden sich nicht immer vollständig voneinander. Manchmal mischen sie unterschiedliche Regeln. Zum Beispiel, in PEAR Coding Standards, die öffnende Klammer "{" geht auf der gleichen Linie wie Kontrollstrukturen, aber sie gehen auf die nächste Zeile nach Funktionsdefinitionen.

BIRNE Stil:


function foo()
{                     // placed on the next line
    if ($maybe) {     // placed on the same line
        do_it_now();
        again();
    } else {
        abort_mission();
    }
    finalize();
}

Beachten Sie auch, dass sie vier Leerzeichen statt Tabulatoren für Einrückungen verwenden.

Hier ist ein Wikipedia-Artikel mit Beispielen verschiedener Einzugsstile.

3 - Vermeiden Sie offensichtliche Kommentare

Deinen Code zu kommentieren ist fantastisch; es kann jedoch übertrieben sein oder einfach nur überflüssig sein. Nimm dieses Beispiel:


// get the country code
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);

// if country code is US
if ($country_code == 'US') {

	// display the form input for state
	echo form_input_state();
}

Wenn der Text so offensichtlich ist, ist es wirklich nicht produktiv, ihn innerhalb von Kommentaren zu wiederholen.

Wenn Sie diesen Code kommentieren müssen, können Sie ihn einfach zu einer einzigen Zeile kombinieren:


// display state selection for US users
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
if ($country_code == 'US') {
	echo form_input_state();
}

4 - Codegruppierung

Meistens erfordern bestimmte Aufgaben ein paar Zeilen Code. Es ist eine gute Idee, diese Aufgaben in separaten Blöcken mit einigen Leerzeichen zwischen ihnen zu halten.

Hier ist ein vereinfachtes Beispiel:



// get list of forums
$forums = array();
$r = mysql_query("SELECT id, name, description FROM forums");
while ($d = mysql_fetch_assoc($r)) {
	$forums []= $d;
}

// load the templates
load_template('header');
load_template('forum_list',$forums);
load_template('footer');

Das Hinzufügen eines Kommentars am Anfang jedes Codeblocks betont auch die visuelle Trennung.

5 - Konsistentes Namensschema

PHP selbst ist manchmal schuldig, nicht konsistenten Namensschemata zu folgen:

strpos () und str_split ()
imagetypes () vs. image_type_to_extension ()

Vor allem sollten die Namen Wortgrenzen haben. Es gibt zwei beliebte Optionen:

camelCase: Der erste Buchstabe jedes Wortes wird groß geschrieben, außer dem ersten Wort.
Unterstriche: Unterstriche zwischen Wörtern wie: mysql_real_escape_string ().

Wenn Sie verschiedene Optionen verwenden, entsteht eine Situation ähnlich der Einzugsstile, wie ich bereits erwähnt habe. Wenn ein bestehendes Projekt einer bestimmten Konvention folgt, sollten Sie damit fortfahren. Einige Sprachplattformen neigen auch dazu, ein bestimmtes Namensschema zu verwenden. In Java verwendet der meiste Code zum Beispiel camelCase-Namen, während in PHP die meisten Unterstriche unterstrichen sind.

Diese können auch gemischt werden. Einige Entwickler bevorzugen die Verwendung von Unterstrichen für prozedurale Funktionen und Klassennamen, verwenden aber camelCase für Klassenmethodennamen:


class Foo_Bar {

	public function someDummyMethod() {

	}

}

function procedural_function_name() {

}

Es gibt also keinen offensichtlichen "besten" Stil. Nur konsequent sein.

6 - TROCKEN-Prinzip

DRY steht für Do not Repeat Yourself. Auch bekannt als DIE: Duplikation ist böse.

Das Prinzip besagt:

"Jedes Wissen muss eine einzige, eindeutige, autoritative Repräsentation in einem System haben."

Der Zweck für die meisten Anwendungen (oder Computer im Allgemeinen) besteht darin, sich wiederholende Aufgaben zu automatisieren. Dieses Prinzip sollte in allen Code- und sogar Webanwendungen beibehalten werden. Das gleiche Stück Code sollte nicht immer wieder wiederholt werden.

Zum Beispiel bestehen die meisten Webanwendungen aus vielen Seiten. Es ist sehr wahrscheinlich, dass diese Seiten gemeinsame Elemente enthalten. Kopf- und Fußzeilen sind in der Regel die besten Kandidaten dafür. Es ist keine gute Idee, Kopien zu behalten, die diese Kopf- und Fußzeilen in jede Seite einfügen. Hier erklärt Jeffrey Way, wie man Vorlagen in CodeIgniter erstellt.


$this->load->view('includes/header');

$this->load->view($main_content);

$this->load->view('includes/footer');

7 - Vermeiden Sie tiefe Verschachtelung

Zu viele Verschachtelungsebenen können das Lesen und Folgen von Code erschweren.


function do_stuff() {

// ...

	if (is_writable($folder)) {

		if ($fp = fopen($file_path,'w')) {

			if ($stuff = get_some_stuff()) {

				if (fwrite($fp,$stuff)) {

					// ...

				} else {
					return false;
				}
			} else {
				return false;
			}
		} else {
			return false;
		}
	} else {
		return false;
	}
}

Aus Gründen der Lesbarkeit ist es normalerweise möglich, Änderungen an Ihrem Code vorzunehmen, um die Verschachtelung zu reduzieren:


function do_stuff() {

// ...

	if (!is_writable($folder)) {
		return false;
	}

	if (!$fp = fopen($file_path,'w')) {
		return false;
	}

	if (!$stuff = get_some_stuff()) {
		return false;
	}

	if (fwrite($fp,$stuff)) {
		// ...
	} else {
		return false;
	}
}

8 - Grenzlinienlänge

Unsere Augen sind komfortabler beim Lesen großer und schmaler Textspalten. Genau aus diesem Grund sehen Zeitungsartikel so aus:

Es empfiehlt sich, horizontal lange Codezeilen nicht zu schreiben.



// bad
$my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();

// good
$my_email
	->set_from('test@email.com')
	->add_to('programming@gmail.com')
	->set_subject('Methods Chained')
	->set_body('Some long message')
	->send();

// bad
$query = "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING(users.id, user_posts.user_id) WHERE post_id = '123'";

// good
$query = "SELECT id, username, first_name, last_name, status
	FROM users
	LEFT JOIN user_posts USING(users.id, user_posts.user_id)
	WHERE post_id = '123'";

Wenn jemand beabsichtigt, den Code aus einem Terminal-Fenster zu lesen, wie z. B. Vim-Benutzer, empfiehlt es sich, die Zeilenlänge auf etwa 80 Zeichen zu begrenzen.

9 - Datei- und Ordnerorganisation

Technisch könnten Sie einen vollständigen Anwendungscode in einer einzigen Datei schreiben. Aber das wäre ein Albtraum, den man lesen und pflegen könnte.

Bei meinen ersten Programmierprojekten wusste ich von der Idee, "Include-Dateien" zu erstellen. Allerdings war ich noch nicht einmal im entferntesten organisiert. Ich habe einen "inc" Ordner mit zwei Dateien erstellt: db.php und functions.php. Als die Anwendungen anwuchsen, wurde auch die Funktionsdatei riesig und nicht mehr zu pflegen.

Einer der besten Ansätze besteht darin, entweder ein Framework zu verwenden oder ihre Ordnerstruktur zu imitieren. So sieht CodeIgniter aus:

10 - Konsistente temporäre Namen

Normalerweise sollten die Variablen beschreibend sein und ein oder mehrere Wörter enthalten. Dies gilt jedoch nicht unbedingt für temporäre Variablen. Sie können so kurz wie ein einzelnes Zeichen sein.

Es empfiehlt sich, konsistente Namen für temporäre Variablen zu verwenden, die die gleiche Art von Rolle haben. Hier sind ein paar Beispiele, die ich in meinem Code verwende:



// $i for loop counters
for ($i = 0; $i < 100; $i++) {

	// $j for the nested loop counters
	for ($j = 0; $j < 100; $j++) {

	}
}

// $ret for return variables
function foo() {
	$ret['bar'] = get_bar();
	$ret['stuff'] = get_stuff();

	return $ret;
}

// $k and $v in foreach
foreach ($some_array as $k => $v) {

}

// $q, $r and $d for mysql
$q = "SELECT * FROM table";
$r = mysql_query($q);
while ($d = mysql_fetch_assocr($r)) {

}

// $fp for file pointers
$fp = fopen('file.txt','w');

11 - Erstellen Sie spezielle SQL-Wörter

Datenbankinteraktion ist ein großer Teil der meisten Webanwendungen. Wenn Sie rohe SQL-Abfragen schreiben, ist es ratsam, sie auch lesbar zu halten.

Obwohl SQL-spezifische Wörter und Funktionsnamen nicht zwischen Groß- und Kleinschreibung unterscheiden, ist es üblich, sie groß zu schreiben, um sie von Ihren Tabellen- und Spaltennamen zu unterscheiden.


SELECT id, username FROM user;

UPDATE user SET last_login = NOW()
WHERE id = '123'

SELECT id, username FROM user u
LEFT JOIN user_address ua ON(u.id = ua.user_id)
WHERE ua.state = 'NY'
GROUP BY u.id
ORDER BY u.username
LIMIT 0,20

12 - Trennung von Code und Daten

Dies ist ein weiterer Grundsatz, der für fast alle Programmiersprachen in allen Umgebungen gilt. Im Fall von Web-Entwicklung, die "Daten" impliziert im Allgemeinen HTML-Ausgabe.

Als PHP vor vielen Jahren zum ersten Mal veröffentlicht wurde, wurde es hauptsächlich als Template-Engine gesehen. Es war üblich, große HTML-Dateien mit ein paar Zeilen PHP-Code dazwischen zu haben. Die Dinge haben sich jedoch im Laufe der Jahre verändert und Websites wurden immer dynamischer und funktionaler. Der Code ist jetzt ein großer Teil von Webanwendungen und es ist nicht länger eine gute Methode, ihn mit HTML zu kombinieren.

Sie können das Prinzip entweder selbst auf Ihre Anwendung anwenden oder Sie können ein Drittanbieter-Tool (Template-Engines, Frameworks oder CMS) verwenden und deren Konventionen befolgen.

Beliebte PHP-Frameworks:

Beliebte Vorlagen-Engines:

Beliebte Content-Management-Systeme

13 - Alternative Syntax innerhalb von Vorlagen

Sie können sich dafür entscheiden, keine ausgefallene Vorlagen-Engine zu verwenden, sondern statt dessen in Ihre Vorlagendateien mit einfachem Inline-PHP zu wechseln. Dies verletzt nicht unbedingt die "Trennung von Code und Daten", solange der Inline-Code direkt mit der Ausgabe verknüpft ist und lesbar ist. In diesem Fall sollten Sie die alternative Syntax für Kontrollstrukturen in Betracht ziehen.

Hier ist ein Beispiel:


<div class="user_controls">
	<?php if ($user = Current_User::user()): ?>
		Hello, <em><?php echo $user->username; ?></em> <br/>
		<?php echo anchor('logout', 'Logout'); ?>
	<?php else: ?>
		<?php echo anchor('login','Login'); ?> |
		<?php echo anchor('signup', 'Register'); ?>
	<?php endif; ?>
</div>

<h1>My Message Board</h1>

<?php foreach($categories as $category): ?>

	<div class="category">

		<h2><?php echo $category->title; ?></h2>

		<?php foreach($category->Forums as $forum): ?>

			<div class="forum">

				<h3>
					<?php echo anchor('forums/'.$forum->id, $forum->title) ?>
					(<?php echo $forum->Threads->count(); ?> threads)
				</h3>

				<div class="description">
					<?php echo $forum->description; ?>
				</div>

			</div>

		<?php endforeach; ?>

	</div>

<?php endforeach; ?>

Auf diese Weise können Sie viele geschweifte Klammern vermeiden. Außerdem sieht der Code so aus und fühlt sich ähnlich an wie HTML strukturiert und eingerückt ist.

14 - Objektorientiert vs. Prozedural

Objektorientierte Programmierung kann Ihnen helfen, gut strukturierten Code zu erstellen. Aber das bedeutet nicht, dass Sie die prozedurale Programmierung komplett aufgeben müssen. Es kann gut sein, eine Mischung aus beiden Stilen zu kreieren.

Objekte sollten zum Darstellen von Daten verwendet werden, die sich normalerweise in einer Datenbank befinden.


class User {

	public $username;
	public $first_name;
	public $last_name;
	public $email;

	public function __construct() {
		// ...
	}

	public function create() {
		// ...
	}

	public function save() {
		// ...
	}

	public function delete() {
		// ...
	}

}

Prozedurale Funktionen können für bestimmte Aufgaben verwendet werden, die unabhängig voneinander ausgeführt werden können.


function capitalize($string) {

	$ret = strtoupper($string[0]);
	$ret .= strtolower(substr($string,1));
	return $ret;

}

15 - Lesen Sie den Open Source Code

Open Source-Projekte werden mit dem Input vieler Entwickler erstellt. Diese Projekte müssen eine hohe Lesbarkeit des Codes gewährleisten, damit das Team so effizient wie möglich zusammenarbeiten kann. Daher ist es eine gute Idee, den Quellcode dieser Projekte zu durchsuchen, um zu beobachten, was diese Entwickler tun.

16 - Code-Refactoring

Wenn Sie "umgestalten", nehmen Sie Änderungen am Code vor, ohne die Funktionalität zu ändern. Sie können es sich wie ein "Aufräumen" vorstellen, um die Lesbarkeit und Qualität zu verbessern.

Dies beinhaltet keine Fehlerkorrekturen oder das Hinzufügen neuer Funktionen. Sie könnten den Code, den Sie am Vortag geschrieben haben, neu gestalten, während er noch frisch in Ihrem Kopf ist, so dass er besser lesbar und wiederverwendbar ist, wenn Sie ihn möglicherweise in zwei Monaten betrachten. Wie das Motto sagt: "früh refaktorieren, oft umgestalten" Sie können während des Refactoring-Prozesses eine der "Best Practices" der Code-Lesbarkeit anwenden.

Ich hoffe, dir hat dieser Artikel gefallen!

Irgendwelche, die ich verpasste? Lass mich über die Kommentare wissen. Lass mich über die Kommentare wissen.