-اصل One Level of Abstraction per Function در کلین کد

برای اینکه مطمئن بشیم تابع ما یک کار انجام میده باید مطئمن بشیم که کد های توی تابع یک سطح انتزاع رو داشته باشن برای اینکه از حالت گنگ بودن در بیاد به این مثال دقت کنید

فک کن شما یه تابع (کدش رو تو کامنتا میفرستم ) دارید بعد یه تیکه از کدتون سطح بالاس مثل getHtml() یه تیکه از کدتون مثل PathParser.render سطح متوسطه و یه تیکه دیگه مث append سطح پایین
در واقع این کد اصل Do One Thing رو اصلا رعایت نکرده

ترکیب کردن لول های مختلف انتزاع باهم توی تابع همیشه باعث گیج شدن ما میشه


#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Switch Statements در کلین کد

این اصل میگه که کوچیک کردن Switch ها سخته و حتی اونایی که 2 تا case دارن هم تا حدی بزرگ محسوب میشن یسری جاها هم ما مجبوریم ازشون استفاده کنیم برای رفع این مشکل میتونیم از پلی مورفیسم (Polymorphism) استفاده کنیم مثلا کد زیر رو در نظر بگیرید

public Money calculatePay(Employee e)
throws InvalidEmployeeType {
    switch (e.type) {
        case COMMISSIONED:
            return calculateCommissionedPay(e);
        case HOURLY:
            return calculateHourlyPay(e);
        case SALARIED:
            return calculateSalariedPay(e);
        default:
            throw new InvalidEmployeeType(e.type);
    }
}

این کد یه سری مشکلات داره :

اول اینکه بزرگه
دوم اینکه بیشتر از یه کار انجام میده
سوم اینکه اصل اول SOLID رو نقض میکنه چون بیشتر از یه دلیل برای تغییر دادنش دارید
چهارم اینکه اصل دوم SOLID رو هم نقض میکنه چون هربار که type جدید اضافه میشه باید تغییر کنه
اما مشکل اصلی اینه که این ساختار ممکنه تو هزارتا فانکشن دیگه هم نیاز بشه

اما چطور حلش کنیم ؟ (کد توی کامنت رو ببینید ) باید ساختار Switch رو توی یک ABSTRACT FACTORY بزاریم تا بیاد از روی switch برامون گزینه های مناسب مشتقات Employee رو بسازه و توابع مختلف مث calculatePay , isPayDay و deliverPay به صورت پلی مورفیسی از طریق اینترفیس Employee وصل بشن بهش

یعنی ما برای راحت شدن از دست سویچا کاری میکنیم که یه بار بنویسیمشون و چند جا استفاده کنیم


پی نوشت : این اصل کمی طولانی بود و سخت بود توی یه پست توضیحش داد از طرفی توی مثال هاش از شی گرایی اونم توی جاوا استفاده کرده و کارمون تا حدودی سخت تر شد برا همین ممکنه یکم گنگ و سخت شده باشه همین که سعی کنید از سوییچ کمتر استفاده کنید و بتونید کدی بنویسید که از یه سوییچ چند بار استفاده کنید کافیه

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Function Arguments در کلین کد

این اصل میگه ایده آل ترین تعداد آرگومان برای یک تابع صفره حالا صفر نشد یدونه آرگومان داشته باشه و اگه مجبور بودید دوتاش تاش بکنید ته تهش سه تا آرگومان یه تابع بیشتر از سه تا آرگومان نباید داشته باشه مگر در شرایطی خاص!

زیاد شدن آرگومان ها برای تست نوشتن هم دردسره فک کن بخوای کلی تست بنویسی تا همه نوع آرگومانی تست بشن و برنامه بدون مشکل باشه . حالا اگه ارگومانی نداشته باشی کارت اسونه یکی داشته باشی یکم سخت تر میشه و به همین ترتیب هرچی ارگومان ها بیشتر باشن کار تست نویسی هم سخت تر میشه


#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Have No Side Effects در کلین کد


این اصل میگه که تابع شما باید یه کار انجام بده اما حواستون باشه که تاثیرات جانبی روی برنامه نداشته باشه که یهو به باگ بخورین و نفهمید از کجا خوردید

مثلا این کد که میاد و یوزر نیم و پسورد رو چک میکنه و اگه اوکی بود true و اگه مشکلی بود false برمیگردونه رو در نظر بگیرید

public class UserValidator {
    private Cryptographer cryptographer;

    public boolean checkPassword(String userName, String password) {
        User user = UserGateway.findByName(userName);
        if (user != User.NULL) {
            String codedPhrase = user.getPhraseEncodedByPassword();
            String phrase = cryptographer.decrypt(codedPhrase, password);
            if ("Valid Password".equals(phrase)) {
                Session.initialize();
                return true;
            }
        }
        return false;
    }
}

این کد ظاهرا اوکیه اما دقت کنید یه قسمت Session.initialize داره که خب از اسم تابع معلوم نیس قراره سشنی درست بشه و خب کسی که کد رو میخونه نمیدونه ریسک پاک شدن سشن فعلی هست


ولی اگه نیازه که اون Session.initialize اونجا باشه بهتره که توی اسم تابع هم بیاد و خواننده کد از اسم تابع بفهمه که اونجا یه سشن initialize میشه و از side effect جلوگیری کنه


لپ کلام اینکه حواستون باشه علاوه بر اینکه تابع یه کار انجام میده در چنین شرایطی باید قسمت های مهم تابع از اسمش معلوم باشه تا تاثیرات جانبی نداشته باشه

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Command Query Separation در کلین کد

این اصل میگه تابع شما یا باید کاری انجام بده یه به سوالی جواب بده اگه هردوتاش رو میکنه بدون که اشتباه میزنی مثلا یه تابع باید یه چیزی رو تو ابجکتی تغییر بده یا یه اطلاعاتی بگیره ازش اگه جفت کار هارو بکنه یکم گیج کننده میشه

مثلا این مثال رو در نظر بگیرید

public boolean set(String attribute, String value);

این کد میاد به یه اتریبیوتی مقداری رو ست میکنه و اگه موفقیت امیز بود ture بر میگردونه و اگه مشکل داشت false میده حالا اگه بیایم اینو توی شرط استفاده کنیم

if (set("username", "CleverDevs"))...

از نگاه خواننده کد ببینید : «این الان چک میکنه که یوزر نیم unclebob از قبل ست شده یا داره چک میکنه »

کلمه set یه فعله ولی وقتی توی شرط استفاده شده قید بنظر میاد و باعث نامفهموم شدن کد میشه
میتونیم به جای set از setAndCheckIfExists استفاده کنیم اما بازم ممکنه برای if statement جالب نباشه بهترین کار اینه که یچیزی مث کد زیر بزنیم :

if (attributeExists("username")) {
      setAttribute("username", "CleverDevs");
       x...
}

خلاصه این اصل این بود که تابعتون نباید هم کاری انجام بده هم چیزی بر گردونه

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Don't Repeat Yourself در کلین کد

تو یه تعریف ساده این اصل میگه که نباید بخش های تکراری تو کدت داشته باشی
مثلا اگه یه الگوریتم داری که میاد و بین هر سه رقم یه قیمت کاما میزاره نیای کپیش کنی هرجا که نیاز بود استفادش کنی
چون اینجوری هر تغییری تو الگوریتم نیاز باشه باید همه جا تک تک عوضش کنی از طرفی کدت شلوغ تر میشه

راه بهتر اینه که بیای و اون کد رو توی تابع مجزا قرار بدی و هرجا نیاز بود تابع رو صدا بزنی

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Comments Do Not Make Up for Bad Code در کلین کد

این اصل خیلی ساده و مختصر میگه که اقا جان اگه دیدی کدی نوشتی و بدرد نخوره کامنتش نکن بجاش اون تیکه کد رو پاک کن
با کامنت کردنش کد هات به شدت کثیف میشن

یه کد واضح با چند خط کامنت خیلی بهتر از یه کد پیچیده با کلی کامنته . وقتی که میزاری پای نوشتن کامنت برای شلختگی کدت بزار روی درست کردن اون شخلتگی


// چپتر قبلی که مربوط به توابع (Functions) بود تموم شد و سعی کردم قسمت های مهم ترشو بزارم میتونید لیستش رو از اینجا ببینید و این چپتر درباره کامنت هاس که سعی میکنم هر از گاهی مطلبی ازش بزارم

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Explain Yourself in Code در کلین کد

این اصل میگه که وقتی میشه کد رو جوری نوشت که خودش کارشو توضیح بده چه نیازی به کامنت اضافس ؟
یعنی چی ؟ مثال پایین رو ببینید

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) &&
      (employee.age > 65))

این کد بهتره یا اینکه جای کامنت این شرط رو توی تابع با اسم درست بزاریم ؟ مثل این

if (employee.isEligibleForFullBenefits())

کلا دوثانیه وقتتون رو میگیره تا جای کامنت این کارو بکنید. بیشتر مواقع اینکه یه تابع بسازی که بتونه کد رو هم توضیح بده بهتر از کامنت نوشتنه

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Good Comments در کلین کد

این اصل چنتا زیر مجموعه داره و کامنت های مفیدی که میتونید بزارید رو گفته تو این پست سعی میکنم به طور خلاصه همشون رو بگم

‏1 - Legal Comments
گاها نیازه که تو اول هر فایل سورس یه سری کامنت در باره ارزش های حقوقی پروژه بزارید مثل این کامنت توی FitNesse

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// Released under the terms of the GNU General Public License version 2 or later.

‏2 - Informative Comments
خوبه که بعضی مواقع یه سریع توضیحات دقیق و مختصر رو کامنت کنیم . البته بهتره تا جایی که میشه اسم تابع این اطلاعات رو بهمون بده ولی اگه نشد یه کامنت بزارید مثلا :

// Returns an instance of the Responder being tested.
protected abstract Responder responderInstance()

‏3 - Explanation of Intent
بعضی مواقع خوبه که قصدی که از نوشتن اون تیکه کد رو داشتید کامنت کنید (با این که در اکثر مواقع نیازی به کامنت نیست)

‏4 - Clarification
گاها خوبه که اون تیکه از کدمون که یه مقدار مبهمه به صورت ساده شده یه کامنت در بارش بزاریم مثلا

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b

‏5 - Warning of Consequences
ممکنه یه تیکه کدی داشته باشید که ران کردنش یه عواقبی داشته باشه حالا چه کم چه زیاد
بهتر براش تو کامنتا هشدار بنویسید که برنامه نویس های دیگه حواسشون باشه

‏6 - TODO Comments
بعضی وقتا قصد دارید که بعدا یک قسمتی رو بهبود بدید یا اضافه کنید اینطور مواقع میتونید TODO بزارید که با TODO // شروع میشه معمولا

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل Bad Comments در کلین کد

این دسته که از کامنت ها که بیشتر کامنت هایی که میزاریم رو شامل میشه کامنت هایی ان که سود خاصی برامون ندارن و الکی کد رو شلوغ میکنن
این اصل چنتا زیر مجموعه داره و کامنت های بدی که میتونید بزارید رو گفته تو این پست سعی میکنم به طور خلاصه همشون رو بگم

‏1 - Mumbling
یعنی اینکه کامنتی بزاری که نامفهمومه و بیشتر از اینکه بدرد بخور باشه باعث سر در گمیه

‏2 - Redundant Comments
یعنی کامنت هایی که بدرد نخور و اضافن و خوندوشون از خوندن کد کد زمان بیشتری میبره

‏3 - Misleading Comments
یعنی یجور لقمه رو دور سر بپیچونی که کسی که کامنت رو میخونه کلا فکر و ذهنش منحرف بشه به یه سمت دیگه

‏4 - Mandated Comments
کامنت هایی که برای هر متغیری مینویسد و معمولا زیاد بدرد نمیخورن مثل javadocs

‏5 - Journal Comments
اینکه بیای و تغییرات پروژه رو هر بار تو کامنتا بزنی ، اینکار برا قبل اومدن سیستم های کنترل ورژن مثل گیت بود این نوع کامنتا الان بدرد نمیخورن

‏6 - Noise Comments
کامنت هایی که کار خاصی ندارن و فقط کد رو شلوغ کردن مثل

/** The day of the month. */

private int dayOfMonth;

‏7 - Commented-Out Code
کامنت کردن کد ها هم یکی از بدترین نوع کامنت هاست

‏8 - Too Much Information
یعنی اینکه تو کامنت اطلاعات زیادی بدی انقدر زیاد باشه خوندنش کلی وقت ببره

این فصل هم تموم شد و میتونید لیستش رو اینجا ببینید

#CleanCode
@CleverDevs - @CleverDevsGp

-اصل The Newspaper Metaphor در کلین کد

این اصل میگه که به یه روزنامه ای که خوب نوشته شده فکر کنید . شما از بالا شروع میکنید و تا پایین میخونیدیش .با خوندن عنوان مقاله می فهمید که اون صفحه در باره چیه و با خوندن پاراگراف اول هم یه خلاصه ای از محتوای صفحه میگیرید.

سورس کد هم تقریبا یه چیز مشابه به اینه شما با خوندن اسم فایل (یا حالا توی oop اسم کلاس) هدف کلی اون سورس فایل رو می فهمید قسمت های بالای کد که میتونه شامل توابع مهم یا متغیر ها و پراپرتی های مهم باشه (مثل پارگراف اول مقاله توی روزنامه) تا کسی که کد رو میخونه خلاصه ای از سورس دستش بیاد.

یه روزنامه شامل بخش های زیادیه که معمولا کوچیکن و در کنار هم با همچین شرایطی قرار گرفتنن تا روزنامه قابل خوندن باشه فرض کنید کل روزنامه فقط یه داستان یا مقاله بلند بود که خوندنش رو سخت میکرد سورس کد هم باید یه شرایط مشابهی داشته باشه تا قالب بندی خوبی داشته باشه یعنی فایل های مختلف با اسم درست و حسابی در کنار هم بیان و بدنه اصلی سورس کد کل برنامه رو بسازن

#CleanCode
@CleverDevs - @CleverDevsGp

Good 🆚 Bad Refactor

وقتی یه پروژه رو میخوایم ریفکتور کنیم چیکارا نکنیم که وضع بدتر شه؟ (این پارت یکه.)

1. Don't Change The Base

بیس کد فعلی رو تا حد امکان تغییر ندید، صرفا شرایط فعلی رو بهتر کنید. مثال:

قبل:

function processUsers(users: User[]) {
  const result = [];
  for (let i = 0; i < users.length; i++) {
    if (users[i].age >= 18) {
      const formattedUser = {
        name: users[i].name.toUpperCase(),
        age: users[i].age,
        isAdult: true
      };
      result.push(formattedUser);
    }
  }
  return result;
}

بعد از یه ریفکتور بد:

import * as R from 'ramda';
const processUsers = R.pipe(
  R.filter(R.propSatisfies(R.gte(R.__, 18), 'age')),
  R.map(R.applySpec({
    name: R.pipe(R.prop('name'), R.toUpper),
    age: R.prop('age'),
    isAdult: R.always(true)
  }))
);

بعد از یه ریفکتور خوب:

function processUsers(users: User[]): FormattedUser[] {
  return users
    .filter(user => user.age >= 18)
    .map(user => ({
      name: user.name.toUpperCase(),
      age: user.age,
      isAdult: true
    }));
}

توی ریفکتور اول بیس کد کلا تغییر کرد و از یه پکیج جدید استفاده شد و احتمال زیاد بقیه کسایی که تو پروژه هستن باهاش آشنایی ندارن و کار برای همه سخت میشه.

#CleanCode SRC
@CleverDevs @CleverDevsGp

-اصل Vertical Openness Between Concepts در کلین کد

کاملا ساده و مختصر این اصل میگه که بین بخش های مختلف کدتون یکی دو خط فضای خالی بزارید فاصله بیوفته بینشون مثلا کد زیر رو ببنید

import CleverDevs from telegram
function helloWorld(){
    console.log("hello world");
}
function sendStarRaction(){
    console.log('send star reaction on CleverDevs Posts');
}

تو کد بالا بین بخش های مختلف کد فاصله ای نذاشتیم حالا اگه کدمون بیشتر و پیچیده تر بشه خوندنش خیلی سخت تر میشه حالا اگه بیایم و مثل کد پایین یه خط خالی بین هر بخشی از کد بزاریم خوندنش به مراتب راحت تر میشه

import CleverDevs from telegram

function helloWorld(){
    console.log("hello world");
}

function sendStarRaction(){
    console.log('send star reaction on CleverDevs Posts');
}

حالا چون تو این پست نمیشد مثال بزرگتری زد اونقدرا تفاوتشون معلوم نمیشه ولی تو کدبیس های بزرگتر رعایت همین یه موضوع تفاوت چشمگیری ایجاد میکنه

#CleanCode
@CleverDevs - @CleverDevsGp