رفتن به مطلب
مرجع رسمی سی‌پلاس‌پلاس ایران
سید معین حسینی

ترجمه راهنمای سبک کد زنی انگولار


پست های پیشنهاد شده

تک مسئولیتی

قانون تک مسئولیتی را به تمام کامپوننت‌ها، سرویس‌ها و نماد‌های دیگر اعمال کنید. این باعث می‌شود که برنامه تمیزتر، خواناتر و امکان نگهداری‌ و تست را داشته باشد.

قانون اول

  • در هر فایل تنها یک چیز، مثل سرویس یا کامپوننت تعریف کنید.

  • در نظر بگیرید که فایل‌ها را به ۴۰۰ خط کد محدود کنید.

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

چرا؟ یک کامپوننت در هر فایل باعث دوری از باگ‌های مخفی‌ای می‌شود که هنگام ترکیب کامپوننت‌ها در یک فایل و اشتراک متغیر‌ها به وجود می‌آیند.

چرا؟ یک کامپوننت تنها می‌تواند خروجی (export) پیشفرض فایل خود باشد که lazy loading در روتر را را آسان می‌کند.

توابع کوچک

  • توابع کوچک تعریف کنید.
  • در نظر بگیرید که توابع را به کمتر از ۷۵ خط کد محدود کنید.

چرا؟ توابع کوچک برای تست راحت‌تر هستند مخصوصا اگر یک کار را انجام دهند و یک نتیجه را داشته باشند.

چرا؟ توابع کوچک باعث استفاده دوباره می‌شوند.

چرا؟ توابع کوچک خواناتر هستند.

چرا؟ توابع کوچک راحت تر نگهداری می‌شوند.

چرا؟ توابع کوچک به دوری از باگ‌های زیر کمک می‌کند:

  • باگ‌هایی که در توابع بزرگ به وجود می‌آیند.

  • باگ‌هایی که به دلیل اشتراک متغیر‌ها با محدوده (scope) خارجی به وجود می‌آیند.

  • ایجاد وابستگی‌های ناخواسته

نام‌گذاری

از نام‌های ثابت برای تمام نماد‌ها استفاده کنید. الگویی را دنبال کنید که خصوصیت و سپس نوع نماد را توضیح دهد.

چرا؟ قرارداد‌های نامگذاری کمک می‌کنند که در یک نگاه راه ثابتی را برای پیدا کردن محتوا فراهم کنید. ثبات در پروژه حیاتی است. ثبات در تیم مهم است. ثبات در یک شرکت بهره‌وری را به شکل چشم‌گیری بالا می‌برد.

چرا؟ قرارداد‌های نام‌گذاری باید پیدا کردن و فهمیدن کد‌های دلخواه را آسان‌تر کنند.

چرا؟ نام پوشه‌ها و فایل‌ها باید به وضوح هدف خود را انتقال دهند. برای مثال:

app/heroes/hero-list.component.ts

احتمالا حاوی کامپوننتی است که لیستی از قرمانان را مدیریت می‌کند.

به اشتراک گذاری این ارسال


لینک به ارسال
به اشتراک گذاری در سایت های دیگر

نام فایل‌ها را با نقطه و خط تیره جدا کنید

  • برای جدا کردن کلمات در نام‌های توصیفی از خط تیره استفاده کنید.
  • برای جدا کردن نام توصیفی از نوع فایل از نقطه استفاده کنید.
  • برای همهٔ کامپوننت‌ها نامی انتخاب کنید که از الگویی ثابت برای توضیح مزیت کامپوننت و سپس نوع آن استفاده کنید.
  • از نام نوع‌های مرسوم از جمله service، component، pipe، module و directive استفاده کنید. در صورتی که مجبور شدید نام نوع اضافی بسازید اما مراقب باشید که تعداد آن‌ها زیاد نشود.

چرا؟ نام نوع‌ها راهی ثابت را برای تشخیص سریع محتوای فایل ارائه می‌کنند.

چرا؟ نام نوع‌‌ها پیدا کردن انواع خاص فایل را در تکنیک جستجوی درهم توسط ویرایش‌گر یا IDE را آسان‌تر می‌کند.

چرا؟ بدون تردید نام نوع‌هایی مثل service توصیف کننده و مشخص هستند. مخفف‌هایی مثل serv، svc و srv می‌توانند گیج کننده باشند.

چرا؟ نام نوع‌ها الگوی شناسایی خاصی ( pattern matching) را برای هر وظیفهٔ خودکار ارائه می‌دهند.

نماد‌ها و نام فایل‌ها

  • برای تمام فایل‌ها، پس از نام چیزی که نشان می‌دهند، از نام‌هایی ثابت استفاده کنید.
  • برای نام‌گذاری کلاس‌ها از نوع نام‌گذاری upper camel case استفاده کنید.
  • نام نماد باید با نام فایل تطابق داشته باشد.
  • به نام نماد‌ها، پسوند‌های قراردادی را اضافه کنید. (مثل: Component، Directive، Module، Pipe یا Service).
  • به فایل‌ها پسوند‌های قراردادی را اضافه کنید. (مثل component.ts، directive.ts،module.ts، pipe.ts، service.ts).

چرا؟ قرارداد‌های ثابت شناسایی و مراجعه سریع به نوع‌های مختلف را آسان می‌کنند.

مثال
نام فایل

نام نماد

app.component.ts

@Component({ ... })

export class AppComponent { }

heroes.component.ts

@Component({ ... })

export class HeroesComponent { }

hero-list.component.ts

@Component({ ... })

export class HeroListComponent { }

hero-detail.component.ts

@Component({ ... })

export class HeroDetailComponent { }

validation.directive.ts

@Directive({ ... })

export class ValidationDirective { }

app.module.ts

@NgModule({ ... })

export class AppModule

init-caps.pipe.ts

@Pipe({ name: 'initCaps' })

export class InitCapsPipe implements PipeTransform { }

user-profile.service.ts

@Injectable()

export class UserProfileService { }

 

به اشتراک گذاری این ارسال


لینک به ارسال
به اشتراک گذاری در سایت های دیگر

نام سرویس‌ها

  • برای تمام سرویس‌ها، پس از نام مزیت آن‌ها از نام‌های ثابتی استفاده کنید.
  • برای نام کلاس سرویس‌ها از پسوند Service استفاده کنید. برای مثال چیزی که داده‌ها و یا نام قهرمانان را می‌گیرد، باید DataService یا HeroService نام‌گذاری شود.
  • بعضی عبارت‌ها به شکل مشخصی سرویس هستند و معمولا ماموریت خود را با تمام شدن با "er" نشان می‌دهند. شما ممکن است ترجیح بدهید سرویسی را که پیام‌‌ها را گزارش می‌کند را Logger بنامید تا این که آن را LoggerService نام‌گذاری کنید. تصمیم بگیرید که آیا این استثنا در پروژه شما مورد قبول است یا خیر.

چرا؟ راهی ثابت را برای شناسایی و مراجعه سریع به سرویس‌ها ارائه می‌کند.

چرا؟ نام‌های مشخص مثل Logger به پسوند نیازی ندارند.

چرا؟ نام سرویس‌هایی مثل Credit، اسم هستند و نیاز به پسوند دارند و وقتی باید پسوند بگیرند که مشخص نیست آیا یک سرویس است یا چیز دیگری.

مثال
نام فایل نام نماد
hero-data.service.ts

@Injectable()

export class HeroDataService { }

credit.service.ts

@Injectable()

export class CreditService { }

logger.service.ts

@Injectable()

export class Logger { }

 

به اشتراک گذاری این ارسال


لینک به ارسال
به اشتراک گذاری در سایت های دیگر

Bootstrapping

  • خود راه‌اندازی (bootstrapping) و منطق پلتفرم (platform) را در فایل main.ts قرار دهید.
  • کنترل ارور (error handling) را هم شامل منطق خود راه‌اندازی قرار دهید.
  • از قرار دادن منطق برنامه در main.ts دوری کنید. در عوض در نظر داشته باشید که آن‌ها را در کامپوننت یا سرویس قرار دهید.

‌‌چرا؟ یک قرارداد ثابت را برای منطق شروع یک برنامه دنبال می‌کند.

چرا؟ یک قرارداد آشنا از پلتفرم های تکنولوژی دیگر را دنبال می‌کند.

انتخاب‌گر کامپوننت ها (selector)

  • برای نام‌گذاری انتخاب‌گرهای کامپوننت‌ها از روش نام‌گذاری کبابی (kebab-case) استفاده کنید.

چرا؟ نام عناصر را با مشخصات عناصر سفارشی ثابت نگه می‌دارد.

به اشتراک گذاری این ارسال


لینک به ارسال
به اشتراک گذاری در سایت های دیگر

پیشوند‌های سفارشی کامپوننت‌ها

  • از یک پیشوند سفارشی برای انتخاب‌گر های کامپوننت‌ها استفاده کنید. برای مثال پیشوند toh نشانگر Tour of Heroes است و پیشوند admin نشانگر محوطهٔ امکانات ادمین است.
  • از پیشوندی استفاده کنید که نشان‌گر محوطهٔ امکانات یا نام خود برنامه (app) باشد.

چرا؟ از تداخل نام کامپوننت‌ها با کامپوننت‌های برنامه‌های دیگر و همچنین عناصر بومی html جلوگیری می‌کند.

چرا؟ به اشتراک گذاری و ترویج کامپوننت را در برنامه‌های دیگر آسان می‌کند.

چرا؟ کامپوننت‌های سفارشی در DOM به راحتی قابل شناسایی هستند.

انتخاب‌گر‌های دایرکتیوها (Directive)

  • برای نامگذاری انتخاب‌گر‌های دایرکتیو‌ها از روش نام‌گذاری شتری کوچک (lower camel case) استفاده کنید.

چرا؟ تجزیه کنندهٔ html انگولار به حروف کوچک و بزرگ حساس است و نوع نامگذاری شتری را می‌شناسد.

پیشوند سفارشی دایرکتیو‌ها

  • برای انتخاب‌گر‌های دایرکتیو‌ها از پیشوند استفاده کنید.
  • انتخاب‌گرهایی که عنصر نیستند را به روش شتری (lower camel case) نام‌گذاری کنید مگر اینکه قرار باشد با نام یکی از ویژگی‌های (attribute) عناصر بومی html همخوانی داشته باشد.

چرا؟ از تداخل نام‌ها جلوگیری می‌کند.

چرا؟ دایرکتیو‌ها را به راحتی قابل شناسایی می‌کند.

نامگذاری پایپ‌ها (Pipes)

  • از روش نامگذاری ثابت برای نامگذاری همهٔ پایپ‌ها به دنبال نام ویژگی آن استفاده کنید.
  • چرا؟ یک راه ثابت برای شناسایی راحت و سریع پایپ‌ها ارائه می‌دهد.

به اشتراک گذاری این ارسال


لینک به ارسال
به اشتراک گذاری در سایت های دیگر

نام فایل‌های تست واحد

  • فایل‌های تست را هم‌نام با کامپوننتی که تست می‌کند نام‌گذاری کنید.
  • فایل‌های تست را با پسوند .spec. نام‌گذاری کنید.

چرا؟ راهی ثابت را برای شناسایی تست‌ها فراهم می‌کند.

چرا؟ الگوی هم‌گام با karma یا راه‌انداز‌های تست دیگر فراهم می‌کند.

نام فایل‌های تست end to end

  • فایل‌های تست e2e را به دنبال نام امکاناتی که تست می‌کند، با پسوند .e2e-spec. نام‌گذاری کنید.

چرا؟ راهی ثابت برای شناسایی سریع فایل‌های تست e2e فراهم می‌کند.

چرا؟ الگویی را مطابق راه‌اندازهای تست و سیستم‌های build خودکار فراهم می‌کند.

نام ماژول (Module) های انگولار

  • به نام نشانهٔ ماژول پسوند Module را متصل کنید.
  • به نام فایل پسوند .module.ts را بدهید.
  • ماژول‌ها را با توجه به نام امکاناتی که ارائه می‌دهد و پوشه‌ای که در آن قرار دارد نام‌گذاری کنید.

چرا؟ راهی ثابت را برای شناسایی و اشاره به ماژول‌ها فراهم می‌کند.

چرا؟ نامگذاری شتری بزرگ ( Upper camel case) برای شناسایی اشیائی که می‌توانند توسط سازنده (constructor) نمونه سازی شوند عمومی است.

‌‌چرا؟‌ به راحتی ماژول را به عنوان ریشهٔ امکاناتی که به همان شکل نامگذاری شده‌اند مشخص می‌کند.

  • ماژول‌های روتینگ (routing) را با پسوند RoutingModule نام‌گذاری کنید.
  • نام یک فایل حاوی ماژول روتینگ را با routing.module.ts تمام کنید.

چرا؟ یک ماژول روتینگ (RoutingModule) ماژولی است که به صورت اختصاصی برای تنظیم کردن روتر (router) انگولار استفاده‌ می‌شود. یک قرارداد ثابت برای نام‌گذاری کلاس‌ها و نام فایل‌ها باعث می‌شوند این ماژول‌ها به راحتی پیدا شده و شناسایی شوند.

به اشتراک گذاری این ارسال


لینک به ارسال
به اشتراک گذاری در سایت های دیگر

به گفتگو ملحق شوید

شما همین الآن می‌توانید مطلبی را ارسال و بعداً ثبت‌نام کنید. اگر حساب کاربری دارید، و با حساب کاربری خود مطلب ارسال کنید.
نکته: مطلب شما قبل از انتشار نیاز به بازبینی توسط میانجی‌گر‌ها دارد.

مهمان
ارسال پاسخ به این موضوع ...

×   شما در حال چسباندن محتوایی با قالب بندی هستید.   حذف قالب بندی

  تنها استفاده از ۷۵ اموجی مجاز می باشد.

×   لینک شما به صورت اتوماتیک جای گذاری شد.   نمایش به عنوان یک لینک به جای

×   محتوای قبلی شما بازگردانی شد.   پاک کردن محتوای ویرایشگر

×   شما مستقیما نمی توانید تصویر خود را قرار دهید. یا آن را اینجا بارگذاری کنید یا از یک URL قرار دهید.


  • کاربران آنلاین در این صفحه   0 کاربر

    هیچ کاربر عضوی،در حال مشاهده این صفحه نیست.

×
×
  • جدید...