نوشته شده توسط پانیذ علیپور

به قواعد نامگذاری پایبند باشید

پلت فرم جاوا مجموعه ای از قواعد نامگذاری داره که به دو دسته تقسیم می شوند : 1. Typographical و 2 . grammatical

تعداد انگشت شماری از قواعد نامگذاری typographical وجود داره که شامل حال package ها ، کلاس ها، اینترفیس ها ، متدها ، فیلدها و متغیرها می شوند.در رعایت این قواعد می بایست دقت شود و تا حد امکان این قواعد نباید زیر پاگذاشته شود و در صورتی که چنین اتفاقی رخ دهد می بایست دلیلی قانع کننده وجود داشته باشد.چنانچه این قواعد در API زیر پا گذارده شود ممکن است در استفاده از آن دچار مشکل شوید .چنانچه در پیاده سازی این قواعد را رعایت نکنید قابلیت نگهداری کدها ممکن است سخت شود.در واقع تخطی از این قوانین سبب گیج شدن دیگر برنامه نویسان و در نهایت منجر به ایجاد خطا می گردد.لذا در یک جمله این قواعد را تا حد امکان زیر پا نگذارید!

دسته اول قواعد TYPOGRAPHICAL


- پکیج ، ماژول


می بایست به صورت سلسله مراتبی از مولفه های تشکیل دهنده اش نامگذاری شوند که این مولفه ها با نقطه از هم جدا می شوند.این مولفه ها شامل حروف کوچک و ندرتا عدد می باشند. تعداد کاراکترهای هرکدام از این مولفه ها نیز می بایست عموما 8 کاراکتر یا کمتر باشد. استفاده از کلمات مخفف با معنی، بیشتر مورد پذیرش است.مثال استفاده از Util بهتر از Utilities است. استفاده از acronym ها قابل قبول هستند.

- کلاس ها و اینترفیس ها(شامل annotation و Enum هم می شود)


نام آن ها بهتر است شامل یک یا چند کلمه باشد که حرف اول آن ها با حرف بزرگ باشد. کلمات اختصاری abbreviation نمی بایست استفاده گردد.به استثنای acronym ها و یا کلمات اختصاری(abbreviation) رایج مثل min, ,max

- متدها و فیلدها


همانند کلاس ها و اینترفیس ها هستند به استثنای اینکه حرف اول آن ها باید کوچک باشد.اگر acronym کلمه اول باشد نیز می بایست با حروف کوچک باشد. تنها استثنا فیلدهای Constant است که نام آن ها می بایست با حروف بزرگ باشند که با _ از هم جدا شوند

- متغیر های محلی


نام آن ها مشابه نامگذاری نام فیلدهای عضو است.به استثنای اینکه abbreviation ،تک کاراکتر و دنباله کوتاهی از کاراکترها که معنی آنها وابسته به زمینه کاری و حوزه تعریف آن هاست قابل قبول می باشد.

- Type Parameter


معمولا شامل تک کاراکتر می باشند.که معمولا شامل یکی از این 5 نوع است:
-T برای نوع دلخواه
- E برای نوع المان از یک مجموعه
- K و V برای نوع کلید ، مقدار از map
- X برای exception ها
-R برای نوع خروجی از یک تابع
در نهایت T,U,V و یا T1,T2,T3 دنباله ای از انواع دلخواه هستند.


دسته دوم که قواعد گرامری است انعطاف پذیر تر از دسته اول هستند.


- پکیج ها


قاعده گرامری برای پکیج ها وجود ندارد.

- کلاس هایی که قابل مقداردهی و instantiate هستند که شامل انواع enum هم می شوند


باید شامل یک اسم یا عبارت اسمی باشد مثل Thread یا PriorityQueue

- کلاس هایی که قابل مقداردهی و instantiate نیستند(کلاس های utility)


با اسم جمع نامگذاری می شوند مثل Collectors

- اینترفیس


همانند کلاس ها و یا با صفتی که به able یا ible ختم می شود نامگذاری می شوند.مثل Rummable

- annotation


Annotation ها چون بسیار پرکاربرد هستند هرکدام از این موارد اسم، فعل، حرف اضافه و صفت قابل استفاده و رایج است.

- متدها


متدهایی که کاری انجام می دهند معمولا با یک فعل و یا عبارت فعلی (شامل مفعول) نامگذاری می شوند همانند append یا drawImage.
متدهایی که مقداری boolean را برمیگردانند معمولا با کلمه is یا has شروع می شوند و در ادامه با یک اسم یا عبارت اسمی یا هر کلمه یا عبارت دیگری که مثل یک صفت عمل کند همراه می شوند.مثل isDigit,isProbablePrime,isEmpty,isEnabled,hasSiblings
متدهایی که مقداری غیر از boolean برمیگردانند معمولا با یک اسم ، عبارت اسمی و یا یک عبارت فعلی که با get آغاز می شود نامگذاری می شوند.مثل size,hashCode,getTime
بعضی متدها می بایست نامگذاری خاص تری داشته باشند مانند متدهایی که نوع یک شی را تبدیل می کنند که معمولا بدین شکل نامگذاری می شوند toType,toString و یا toArray
متدهایی که نما یا view از یک شی را برمیگردانند به صورت asType نامگذاری می شوند.همانند asList
متدهایی که مقداری primitive با همان مقدار از شی ورودی را برمیگردانند typeValue نامگذاری می شوند مثل intValue نام های رایج برای static factory ها from,of,valueOf,instance,getInstance,newInstance,getTypeو newType است

- فیلدها


قواعد گرامری برای این دسته مهم نیست.فقط فیلدهای boolean معمولا مانند متدهای accessorنامگذاری می شوند به استثنای is که از ابتدای آن ها حذف می شود.مثل initialized همچنین فیلدها با اسم یا یک عبارت اسمی نامگذاری می شوند.

پینوشت : تفاوت acronym با abbreviation : تو معنی بنظر یکی میان من خودم تا این حد به تفاوت ظریفشون پی نبرده بودم، acronym در واقع از حروف اول یک عبارت تشکیل میشه و نوع تلفظش هم به نسبت عبارت اولیه و اصلیش متفاوته مثل

IUPAC: International Union of Pure and Applied Chemistry
که تلفظش هم I-U-pak هست.

ولی abbreviation تنها نسبت به عبارت اولیه و اصلیش متفاوت نوشته میشه اما همونطوری خونده میشه مثل Etc. که همون et cetera خونده میشه. تنها تفاوت کلیدی این دو کلمه تو تلفظشون نسبت به عبارت و یا کلمه اصلیشونه.