└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | مفاهیم و اصول اصلی کدنویسی تمیز با مثال
  2 | 
  3 | ۱- خوانایی (Readability): کد باید به قدر کافی خوانایی داشته باشد. برنامه‌نویسان بیشتر از خواندن کد تا نوشتن آن درگیر هستند. کد خوانایی، توجیه‌پذیر و مفهوم، برنامه‌نویسان دیگر را به‌سهولت به درک کد هدایت می‌کند.
  4 | # بد
  5 | x = "ThisIsAVariableThatStoresTheUserName"
  6 | 
  7 | # خوب
  8 | user_name = "JohnDoe"
  9 | 
 10 | ------------------------------------------------------------
 11 | 
 12 | 
 13 | ۲- نام‌گذاری مناسب (Meaningful Names): نام‌گذاری باید توصیفی و معنی‌دار باشد. نام متغیرها، توابع، کلاس‌ها و ... باید اطلاعات کافی را انتقال دهد تا برنامه‌نویسان دیگر بدون نگاه به جزئیات کد، بفهمند چه کاری انجام می‌شود.
 14 | 
 15 | // بد
 16 | function fn(x) {
 17 |   return x * 2;
 18 | }
 19 | 
 20 | // خوب
 21 | function calculateDouble(value) {
 22 |   return value * 2;
 23 | }
 24 | 
 25 | ------------------------------------------------------------
 26 | 
 27 | ۳- توابع کوچک (Small Functions): توابع باید اندازه‌ی کوچکی داشته باشند و یک کار خاص را انجام دهند. هر تابع باید تنها یک سطح انتزاع داشته باشد و وظیفه‌ی خاص خود را اجرا کند.
 28 | 
 29 | # بد
 30 | def process_data(data):
 31 |   # کد زیاد
 32 |   # ...
 33 |   # ...
 34 |   # ...
 35 |   return result
 36 | 
 37 | # خوب
 38 | def process_data(data):
 39 |   result = process_step1(data)
 40 |   result = process_step2(result)
 41 |   result = process_step3(result)
 42 |   return result
 43 | 
 44 | def process_step1(data):
 45 |   # کد مرتبط با مرحله ۱
 46 |   pass
 47 | 
 48 | def process_step2(data):
 49 |   # کد مرتبط با مرحله ۲
 50 |   pass
 51 | 
 52 | def process_step3(data):
 53 |   # کد مرتبط با مرحله ۳
 54 |   pass
 55 | 
 56 | 
 57 | 
 58 | ------------------------------------------------------------
 59 | 
 60 | 
 61 | ۴- یکسانی (Consistency): استفاده از یک الگو و یک استایل در کل کد به خوانایی و درک کد کمک می‌کند. کدهای یکسان به برنامه‌نویسان کمک می‌کنند تا الگوها و رفتارهای مشابه را تشخیص دهند.
 62 | 
 63 | // بد
 64 | function calculateArea(length, width) {
 65 |   // کد محاسبه مساحت
 66 | }
 67 | 
 68 | // خوب
 69 | function calculateRectangleArea(length, width) {
 70 |   // کد محاسبه مساحت
 71 | }
 72 | 
 73 | 
 74 | ------------------------------------------------------------
 75 | 
 76 | 
 77 | ۵- مسئولیت یکتا (Single Responsibility Principle - SRP): هر کلاس یا تابع باید مسئولیت یکتایی داشته باشد. این اصل از SOLID principles گرفته شده است.
 78 | 
 79 | # بد
 80 | class User:
 81 |   def process_data(self, data):
 82 |     # کد پردازش داده
 83 |     pass
 84 | 
 85 | # خوب
 86 | class DataProcessor:
 87 |   def process_data(self, data):
 88 |     # کد پردازش داده
 89 |     pass
 90 | 
 91 | 
 92 | 
 93 | 
 94 | ------------------------------------------------------------
 95 | 
 96 | 
 97 | ۶- نبايد اطلاعات داخلي را باز كرد (Encapsulation): کلاس‌ها باید جزئیات داخلی خود را پنهان کنند و تنها واسطه‌های لازم را ارائه دهند.
 98 | 
 99 | // بد
100 | class BankAccount:
101 |   def __init__(self, balance):
102 |     self._balance = balance
103 | 
104 | # خوب
105 | class BankAccount:
106 |   def __init__(self, balance):
107 |     self.balance = balance
108 | 
109 | ------------------------------------------------------------
110 | 
111 | 
112 | ۷- کد تکراری (DRY - Don't Repeat Yourself): اصل DRY تکرار کد را کاهش داده و از استفاده‌های تکراری جلوگیری می‌کند. اگر یک قطعه کد در چندین جای کد تکرار شده باشد، باید آن قطعه را در یک مکان مشخص قرار داد.
113 | 
114 | 
115 | // بد
116 | function calculateRectangleArea(length, width) {
117 |   return length * width;
118 | }
119 | 
120 | function calculateSquareArea(side) {
121 |   return side * side;
122 | }
123 | 
124 | // خوب
125 | function calculateArea(length, width) {
126 |   return length * width;
127 | }
128 | 
129 | 
130 | ------------------------------------------------------------
131 | 
132 | 
133 | ۸- تست پذیری (Testability): کد باید به‌سهولت تست‌پذیر باشد. این به‌معنای طراحی به‌گونه‌ای است که بتواند به‌سهولت تست شود و خطاها به‌راحتی شناسایی شوند.
134 | 
135 | 
136 | # بد
137 | def calculate_area(length, width):
138 |   # کد محاسبه مساحت
139 |   pass
140 | 
141 | # خوب
142 | def calculate_area(length, width):
143 |   # کد محاسبه مساحت
144 |   pass
145 | 
146 | def test_calculate_area():
147 |   # تست محاسبه مساحت
148 |   pass
149 | 
150 | 
151 | ------------------------------------------------------------
152 | 
153 | 
154 | ۹- نگاه به جلو (Forward Looking): طراحی کد باید به آینده نیز نگاه کند. باید قابلیت توسعه و افزودن ویژگی‌های جدید را داشته باشد.
155 | 
156 | // بد
157 | function calculate_discount(price, discount_rate):
158 |   # کد محاسبه تخفیف
159 |   pass
160 | 
161 | // خوب
162 | function calculate_discount(price, discount_rate, additional_discount):
163 |   # کد محاسبه تخفیف
164 |   pass
165 | 
166 | 
167 | ------------------------------------------------------------
168 | 
169 | 
170 | ۱۰- تفکر نهایی (Ultimate Simplicity): کد باید به حداقل سادگی و پیچیدگی رسانده شود. اصول KISS (Keep It Simple, Stupid) و YAGNI (You Ain't Gonna Need It) در این‌جا مورد تأکید قرار می‌گیرند.
171 | 
172 | 
173 | # بد
174 | def complicated_algorithm(x, y, z):
175 |   # کد پیچیده و سخت
176 |   pass
177 | 
178 | # خوب
179 | def simple_algorithm(x, y):
180 |   # کد ساده و قابل فهم
181 |   pass
182 | 


--------------------------------------------------------------------------------