代碼注釋和解析

簡介

技術文章里，避免不了的，會帶有大量的注釋，本篇文章討論代碼注釋和代碼講解時需要注意的地方。

1. 避免無用的注釋

很多時候是代碼生成器生成的，如下：

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class UsersAddEmailVerified extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->boolean('email_verified')->default(false)->after('remember_token');
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('email_verified');
        });
    }
}

此時應刪除掉注釋，原因如下：

刪除以后，干凈也專注很多了：

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class UsersAddEmailVerified extends Migration
{
    public function up()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->boolean('email_verified')->default(false)->after('remember_token');
        });
    }

    public function down()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('email_verified');
        });
    }
}

2. 善用注釋來講解大塊代碼

大塊代碼在文章中講解，經常會遇到以下的問題：

一個合理的做法是，直接在代碼里添加注釋，這樣可讀性要好多了：