メインコンテンツまでスキップ

AGL Coding Rules

Cấu hình chung cho Editor​

  • Encoding là UTF-8
  • Line break code (End of Line Sequence) dùng LF
  • Thụt đầu dòng (indent) dùng tab (2 khoảng trắng).

Ví dụ: Cấu hình cho VS code trong settings.json:

{
  "files.encoding": "utf8", /* Encoding is UTF-8 */
  "files.eol": "\n", /* Line break code is LF */
  "editor.tabSize": 2, /* Tab is 2 half-width spaces */
}

Đặt tên File/Directory​

  • Các ký tự được dùng để đặt tên cho File/Directory như sau:
    • Chữ viết thường từ "a" đến "z" (1 byte)
    • Chữ số từ "0" đến "9" (1 byte)
    • Ký tự "-" (gạch ngang), "_" (gạch dưới) (1 byte)
  • Đặt tên bằng tiếng Anh
  • Không dùng space (khoảng trắng) và các kí tự đặc biệt khác
  • Nếu tên File/Directory có nhiều từ, hãy thêm dấu "-" (gạch ngang) giữa các từ.

Markup​

  • Luôn có khai báo <!DOCTYPE html> và <html lang="ja">.
  • Validate HTML W3C
  • Viết HTML đúng cú pháp, đúng thẻ.
  • Tên thẻ và thuộc tính đều phải viết bằng chữ viết thường.
  • Không thêm các thư viện CDN mà bạn không sử dụng, nếu sử dụng nhiều CDN nên quy về 1 CDN duy nhất.

Các thẻ meta​

  • Đảm bảo charset="UTF-8"
  • Đảm bảo thẻ title, description, keyword nằm bên trong thẻ head. (Có thể để trống khi không có chỉ thị).

Các thẻ heading​

  • 1 page chỉ có duy nhất 1 thẻ <h1>, thẻ <h1> không chứa logo mà chứa 1 title trọng điểm của page đó.
  • Sử dụng các thẻ heading trong trang phù hợp với cấu trúc logic của tài liệu.
    • Nếu đã có thẻ <h4> thì phải có thẻ <h3>, <h2> ở trước
    • Font-size của các thẻ heading trong section phải đảm bảo quy tắc h2 > h3 > h4 > h5 > h6
  • Thẻ heading thường được chứa bởi các thẻ setion, aside, article.

Thẻ liên kết/button​

  • Chỉ định href="#" nếu liên kết chưa xác định rõ đích đến.
  • Liên kết bên ngoài phải được thiết lập target="_blank".
  • Chú ý vùng phủ link, phải phủ link đúng vị trí của link.
  • Link phải là block, không được để là target đơn.
  • Tất cả các liên kết đều phải thiết lập hover mặc định là opacity: 0,7 và transition, trừ khi khách hàng có chỉ định khác.
  • Đảm bảo các phần tử liên kết/button được áp dụng cài đặt cursor: pointer.

Thẻ img, picture​

  • Thẻ img bắt buộc phải có alt, alt chứa title chính của section hoặc của item, alt của logo là tên website.
  • Thêm thuộc tính loading="lazy" vào các thẻ img, trừ hình ảnh ở màn hình đầu tiên (first view) hoặc người yêu cầu có thỉ thị khác.
  • Khi sử dụng hình ảnh khác nhau tùy theo thiết bị hoặc độ rộng của màn hình, hãy sử dụng thẻ picture.
  • Đảm bảo hình ảnh không bị biến dạng khi responsive.
  • Đảm bảo hình phải có tỉ lệ x2 trên Mobile và màn hình Rentina.
  • Không cần thiết phải sử dụng thuộc tính type.
  • Khi sử dụng Google Font, nên dùng thẻ <link> không nên dùng import trong CSS để tối ưu việc tải trang.

Thẻ dl, dt, dd​

  • Thường sử dụng cho FAQ list

Các thẻ html5​

  • Thẻ main chỉ sử dụng 1 lần cho nội dung chính (main content).
  • Thẻ nav chỉ sử dụng 1 lần cho Global navigation.
  • Trong section phải có ít nhất 1 thẻ heading, nếu không hãy dùng div.
  • Thẻ time dùng để hiển thị ngày giờ cho bài viết/sự kiện.

Styling​

CSS​

  • Validate CSS W3C

  • font-size, line-height, letter-spacing phải được chỉ định bằng các giá trị tương đối (rem, em,...), trừ các trường hợp đặc biệt.

    /* Bad */
    .elem {
      font-size: 14px;
      line-height: 21px;
      letter-spacing: 1.4px;
    }

    /* Good */
    .elem {
      font-size: 1.4rem;
      line-height: 1.5;
      letter-spacing: 0.1em;
    }

  • Thuộc tính (property) và giá trị của thuộc tính phải sử dụng chữ viết thường.

    /* Bad */
    .elem {
      COLOR: #FFF;
      background-color: RED;
    }

    /* Good */
    .elem {
      color: #fff;
      background-color: red;
    }

  • Khi sử dụng một thuộc tính nào đó, phải đảm bảo thuộc tính đó được sử dụng phổ biến trên toàn bộ trình duyệt (Cross-Browser), nếu không thì phải hỏi lại ý kiến khách.

  • Hạn chế sử dụng id để viết CSS (trừ những trường hợp bất khả kháng không thể tự đặt class)

  • Hạn chế sử dụng !important càng ít càng tốt.

SCSS​

  • Hạn chế cấp độ càng ít càng tốt (chỉ lồng trong vòng 3 cấp độ).

  • Không lạm dụng mixin vì có một vài trường hợp không tối ưu được code khi build ra CSS thuần.

  • Không gọi thẳng tên html element trong SCSS mà phải gọi tên Class, trừ trường hợp bắt buộc như ở trang single của wordpress.

    <div class="c-box">
      <h2 class="c-box__title">title title title title title</h2>
      <p class="c-box__desc">desc desc desc desc desc desc desc desc</p>
    </div>
    /* Bad */
    .c-box { 
      padding: 20px;
      h2 {
        color: blue;
      }
    }

    /* Good */
    .c-box { 
      padding: 20px;
      &__title {
        color: blue;
      }
    }

  • Đặt media queries ngay tại class cần thay đổi.

    /* Bad */
    .c-block {
      background-color: #fff;

      &__element {
        color: #000;
      }
    }

    @media (max-width: 767px) {
      .c-block {
        background-color: #000;
      
        &__element {
          color: #fff;
        }
      }
    }

    /* Good */
    .c-block {
      background-color: #fff;

      @media (max-width: 767px) {
        background-color: #000;
      }

      &__element {
        color: #000;

        @media (max-width: 767px) {
          color: #fff;
        }
      }
    }

Flocss & BEM​

  • Đặt tên Class theo Flocss và BEM.

  • Không cần đặt Class cho tất cả các thẻ.

    <!--Ví dụ đặt tên Class-->
    <div class="c-sample">
      <figure class="c-sample__img">
        <img class="c-sample__img__img1" alt="img" src="/">
      </figure>
      <div class="c-sample__text c-sample__text--red">
        <p class="c-sample__text__text1">title title title</p>
      </div>
    </div>

  • Tránh đặt tên Class quá dài và đặt tên lồng nhiều Class cha.

    <!-- Bad -->
    <div class="c-list">
      <div class="c-list__card">
        <div class="c-list__card__info"> <!-- Not recommended -->
          <figure class="c-list__card__info__img"> <!-- Not recommended -->
            <img alt="img" src="/">
          </figure>
          <div class="c-list__card__info__text"> <!-- Not recommended -->
            Title title title
          </div>
        </div>
      </div>
    </div>

    <!-- Good -->
    <div class="c-list">
      <div class="c-list__card">
        <div class="c-list__info">
          <figure class="c-list__img">
            <img alt="img" src="/">
          </figure>
          <div class="c-list__text">
            Title title title
          </div>
        </div>
      </div>
    </div>

Fonts​

  • Đối với Fonts, khi coding phải đảm bảo giống theo design mà khách hàng đã giao.
  • Các trường hợp chưa rõ ràng hoặc không có font thì phải lập tức liên hệ khách hàng.
  • Tuyệt đối không được tự ý download font ở trên mạng, và sử dụng file font để convert sang font-face mà không có sự xác nhận của khách hàng. Đa số các font tiếng Nhật đều có bản quyền, nếu bạn sử dụng một cách tùy tiện thì sẽ vi phạm pháp luật.
  • Font family phải có Font Fallbacks (sans-serif, serif...) ở đuôi.
  • Main font phải định chung cho 1 thẻ bao quát lớn nhất, thông thường sẽ là thẻ body.
    body {
      font-family: "游ゴシック", YuGothic, "ヒラギノ角ゴ Pro", "Hiragino Kaku Gothic Pro", "メイリオ", "Meiryo", sans-serif;
    }
  • Font size phải sử dụng đơn vị rem, chỉ cho phép số lượng số thập phân là 1.
    Ví dụ: font-size: 2.5rem.

Javascript​

Hằng số (Constant)​

Các hằng số được sử dụng xuyên suốt và không thay đổi phải được khai báo bằng chữ IN HOA + dấu "_ (gạch dưới)".

const SITE_URL = 'https://...';

Biến (Variables) và Hàm (Functions)​

Các biến/hàm trong JavaScript được khai báo bằng kiểu camelCase với ký tự viết thường ở đầu, các từ sau viết HOA chữ cái đầu

var companyName = 'Allgrow Labo';

function showName(name) {
  console.log(name);
}

Library​

Slider/Carousel​

  • Cài đặt mặc định chế độ autoplay.
  • Ưu tiên sử dụng Swiper

Paralax​

Perfect Pixel​

Sản phẩm tạo ra phải giống 100% so với thiết kế ngoại trừ các trường hợp khách quan do design hoặc khách hàng không yêu cầu

Trình duyệt và thiết bị​

Đảm bảo trang web của bạn được tạo ra sẽ chạy tốt trên các trình duyệt (Cross-Browser) và thiết bị thật (Cross-Device) sau:

HĐHTrình duyệtThiết bị
WindowsChrome, Firefox, EdgeWindow PC
MacOSSafariiMac, Macbook
iOSSafariiPhone, iPad
AndroidChromeAndroid Device

Breakpoint và môi trường giả lập​

Về cơ bản, đa số thiết kế đều yêu cầu thực hiện công việc responsive, mỗi thiết kế sẽ có những yêu cầu về breakpoint khác nhau.
Nếu không có yêu cầu cụ thể, tiêu chí cho breakpoint sẽ mặc định như sau:

Kích thướcĐiểm cần kiểm traMôi trường giả lập
1025px trở lênBố cục không bị vỡPC
768px~1024pxBố cục không bị vỡTablet
320px~767pxBố cục không bị vỡSP
ghi chú

Có thể thêm breakpoint để thuận tiện cho việc Responsive và Perfect Pixel

Wordpress​

  • Đảm bảo không phát sinh lỗi về giao diện sau khi chuyển từ HTML sang WordPress.
  • Phân chia layout thành các file VD như header.php, footer.php, sidebar.php... một cách chính xác.
  • Các trang không tồn tại HTML thì cho hiển thị trang 404 một cách chính xác.
  • Nhớ đặt ngôn ngữ chính của trang admin là tiếng Nhật, có thể chỉnh về tiếng Anh trong lúc chỉnh sửa nhưng sau khi chỉnh sửa xong phải trả về tiếng Nhật.
  • Set màu nền mặc định cho trang admin.
  • Nhớ phải active menu.
  • Phải chú ý và xử lý phân trang một cách chính xác.
  • Sử dụng các hàm mặc định của WordPress theo đúng chức năng của nó, ví dụ:
    • Header: dùng hàm get_header() để include file header.php, lưu ý nhớ đặt hàm wp_head() trong file header.php.
    • Footer: dùng hàm get_footer() để include file footer.php, lưu ý nhớ đặt hàm wp_footer() trong file footer.php.
    • Get link: dùng hàm get_template_directory_uri() để gắn link cho các file css, js.
    • Vòng lặp (loop): Ở single page cũng cần sử dụng vòng lặp (loop), dùng wp_reset_postdata() để kết thúc vòng lặp.
  • Khi code chú ý việc code bị dư thừa hoặc code không sử dụng, phải luôn suy nghĩ về sự tối ưu.
  • Hiểu rõ cấu trúc file template của Wordpress và thứ tự ưu tiên đọc template.
  • Hãy cài đặt title, meta description chính xác cho toàn bộ các page.
  • Các CSS trên trang single cần sử dụng tên html element thay vì tên class
    .content {  
      h1 { ... }  
      h2 { ... }  
      p  { ... }  
      ul { ... } 
      ... 
    }

PHP​

  • Tên biến/hàm trong PHP được khai báo bằng kiểu camelCase.
  • Các hằng số phải viết hoa tất cả các chữ, cách nhau bằng dấu "_" (gạch dưới).
  • Code PHP phải được viết trong cặp thẻ <?php ?> và sử dụng cặp thẻ ngắn <?= ?> thay cho echo.

Yêu cầu về bảo mật thông tin​

  • Không chia sẻ thông tin về dự án (design, source code, data...) tới bên thứ 3 (kể cả nhân viên của AGL) khi không được phép
  • Không công khai dự án lên SNS trước khi release.