Clean code — নাম, function, comment, formatting আর error handling

১ · Clean code মানে কী — পড়া সহজ, বদলানো সহজ

আগের তিনটি পর্বে (পর্ব ৩৮ software architecture, পর্ব ৩৯ MVC আর MVVM, পর্ব ৪০ clean আর hexagonal architecture) বড় ছবিটা দেখেছেন — system-কে স্তরে আর অংশে ভাগ করা। এবার আমরা নামব একেবারে নিচে, প্রতিদিনের লেখা লাইনে। নাম মিলে গেলেও গুলিয়ে ফেলবেন না: clean architecture হলো অংশগুলোর নির্ভরতার দিক নিয়ে একটি নকশা, আর clean code হলো প্রতিটি function, নাম আর লাইনের পাঠযোগ্যতা নিয়ে অভ্যাসের সমষ্টি।

Clean code-এর কোনো একটি সর্বসম্মত সংজ্ঞা নেই, কিন্তু প্রায় সব সংজ্ঞায় তিনটি কথা ফিরে ফিরে আসে:

কেন এত জোর? কারণ কোড লেখার চেয়ে পড়া হয় অনেক বেশি। Robert C. Martin তাঁর বই Clean Code: A Handbook of Agile Software Craftsmanship-এ (২০০৮) অনুমান করেন যে পড়া আর লেখার সময়ের অনুপাত ১০:১-এরও বেশি। এটি তাঁর অভিজ্ঞতার আন্দাজ, কোনো মাপা গবেষণার ফল নয় — তবু দিকটা প্রায় সবাই স্বীকার করেন: একটি লাইন একবার লেখা হয়, তারপর review-তে, bug খোঁজায়, নতুন feature যোগের সময়, বছরের পর বছর পড়া হয়। আরও পুরোনো একটি বাক্য আছে Abelson ও Sussman-এর Structure and Interpretation of Computer Programs (১৯৮৫) বইয়ের ভূমিকায়: program লেখা উচিত মানুষের পড়ার জন্য, আর শুধু প্রসঙ্গক্রমে যন্ত্রের চালানোর জন্য।

পর্ব ০৩-এ (software quality) দেখেছেন, ISO/IEC 25010-এ maintainability-র উপ-গুণের মধ্যে আছে analysability আর modifiability — অর্থাৎ বোঝা আর বদলানোর সহজতা। Clean code এই দুটি গুণের হাতে-কলমে রূপ; আর পর্ব ২৬-এর (নকশার নীতি) নীতিগুলো এখানে লাইনের স্তরে প্রয়োগ হবে।

পুরো পর্ব জুড়ে একটি উদাহরণ চলবে: একটি কোচিং সেন্টারের ভর্তি আর ফি-হিসাবের app (কাল্পনিক). শিক্ষার্থী online বা offline batch-এ কয়েক মাসের জন্য ভর্তি হন; ভর্তি পরীক্ষায় ৮০ বা বেশি পেলে মেধা-ছাড়, ছয় মাসের বেশি কোর্সে এককালীন ছাড়, দেরিতে ফি দিলে জরিমানা, আর নির্দিষ্ট শর্তে টাকা ফেরত।

২ · নাম — কোডের সবচেয়ে বড় documentation

Program-এ variable, function, class, module — যা কিছুর নাম দিই, সবই identifier. একটি প্রচলিত রসিকতা (সাধারণত Phil Karlton-এর নামে): computer science-এ কঠিন কাজ মাত্র দুটি — cache invalidation আর নাম দেওয়া। ভালো নাম দিতে হলে আগে বুঝতে হয় জিনিসটা আসলে কী।

একটি উদ্দেশ্য-প্রকাশক নাম (intention-revealing name) তিনটি প্রশ্নের উত্তর দেয়: জিনিসটা কেন আছে, কী করে, আর কীভাবে ব্যবহার হয়। নাম পড়ার পরেও comment লাগলে নামটা কাজ শেষ করেনি। নামের দৈর্ঘ্য তার পরিধির সাথে মানানসই: তিন লাইনের loop-এ i ঠিক, কিন্তু পুরো module-এ ব্যবহৃত মানের নাম i হলে দুশো লাইন পরে কেউ বুঝবেন না। এককের গুরুত্ব মনে করিয়ে দেয় পর্ব ০২-এর (software-এর ইতিহাস) Mars Climate Orbiter-এর ঘটনা।

Hungarian notation আর নামকরণের রীতি

Hungarian notation হলো নামের শুরুতে type-এর সংকেত বসানো: strName (string), iCount (integer), bIsPaid (boolean). রীতিটি Charles Simonyi-র নামে পরিচিত (তিনি হাঙ্গেরীয় বংশোদ্ভূত)। তখনকার editor type দেখাত না, তাই এর প্রয়োজন ছিল। আজ editor নিজেই type দেখায়, আর type বদলালে নামটি মিথ্যা হয়ে যায়; তাই বেশিরভাগ আধুনিক style guide এটি নিরুৎসাহিত করে (ইতিহাস আর একটি “ভালো” রূপ ভাবনার প্রশ্ন ৩-এ)।

Type-এর সংকেত না দিলেও প্রতিটি ভাষার একটি নামকরণের রীতি আছে, আর দলের সবাই সেটি মানলে কোড এক হাতের লেখা মনে হয়। Python-এ PEP 8 অনুযায়ী variable ও function snake_case, class PascalCase, constant UPPER_SNAKE_CASE; JavaScript-এ প্রচলিত রীতি camelCase, class PascalCase. Python-এর রীতি নিয়ে বিস্তারিত দেখুন Python কোর্সের Pythonic কোড পর্বে।

Boolean-এর নাম — প্রশ্নের মতো পড়া যায় এমন

Boolean মান সত্য বা মিথ্যা — তাই তার নাম একটি হ্যাঁ/না প্রশ্নের মতো হওয়া উচিত: is_paid, has_merit_discount, can_refund, should_send_sms. তখন if is_paid: একটি বাক্যের মতো পড়া যায়। flag, status, ok কিছুই বলে না — কিসের ok? নামে নেতিবাচকতাও এড়িয়ে চলুন: if not is_not_unpaid পড়লে মাথা ঘোরে।

ইংরেজি নাকি বাংলায় নাম?

অনেকে অবাক হন যে Python 3 আর JavaScript দুটিই Unicode অক্ষরে নাম দিতে দেয় — Python-এ এটি PEP 3131 থেকে এসেছে। অর্থাৎ মোট_ফি = 1200 * 3 লিখলে Python ঠিকঠাক চলে, আর JavaScript-এ let মোট_ফি = 3600-ও বৈধ। তবে বাস্তবে বেশিরভাগ দল — সাধারণত বাংলাদেশেও — Unicode identifier নয়, ইংরেজি নাম রাখে: library আর documentation ইংরেজিতে, সব tool-এ বাংলা টাইপ সমান সহজ নয়, বাইরের সহকর্মী পড়তে পারেন না, আর দেখতে-একই Unicode অক্ষর নিরাপত্তা-ঝুঁকিও আনতে পারে (ভাবনার প্রশ্ন ৫)। প্রচলিত মাঝের পথ: নাম ইংরেজিতে (zakat_amount, eid_bonus), ব্যবহারকারীকে দেখানো লেখা বাংলায় — আর সিদ্ধান্তটি দলের style guide-এ লেখা।

একটি নাম ধাপে ধাপে

নিচের stepper-এ একটি পুরোনো function-এর নাম একটি একটি করে বদলানো হচ্ছে; আচরণ একই থাকে। খেয়াল করুন function যেখানে ডাকা হয় (call site), সেখানে কী বদলায়।

def calc(d, m, f):
    ...
total = calc(12, 90, True)    # 12 কী? 90 কী? True কী?

def calc(months, m, f):
    ...
total = calc(12, 90, True)

def calc(months, exam_marks, f):
    ...
total = calc(12, 90, True)

def calc(months, exam_marks, is_online):
    ...
total = calc(12, 90, True)    # call site-এ এখনো True

def calc(months, exam_marks, mode):   # "online" | "offline"
    ...
total = calc(12, 90, "online")

def course_fee(months, exam_marks, mode):
    ...
total = course_fee(12, 90, "online")

নামের নিয়মগুলো কিছুটা যন্ত্র দিয়েও যাচাই করা যায়। নিচের প্রোগ্রামটি একটি খেলনা linter — এমন tool যা কোড না চালিয়েই সন্দেহজনক ধরন খোঁজে। এটি Python-এর নিজস্ব ast module দিয়ে কোডকে abstract syntax tree-এ ভেঙে তিনটি নিয়ম দেখে: loop-এর বাইরে এক-অক্ষরের নাম, Hungarian-ধাঁচের type সংকেত, আর is_/has_/can_ ছাড়া boolean. এটি শুধু শেখার জন্য; আসল কাজে Pylint-এর invalid-name বা Ruff-এর pep8-naming নিয়মের মতো tool ব্যবহার হয়, আর linter-এর পুরো আলোচনা পর্ব ৪৪-এ (code review).

# A toy naming linter (for teaching only, not a real tool) using Python's ast.
import ast, re
SOURCE = '''
def calc(d, m, flag=True):
    strName = "fee"
    ok = m >= 80
    for i in range(3):
        t = d * i
    is_merit = m >= 80
'''
HUNGARIAN = re.compile(r"^(str|int|lst|arr|dict|obj|sz|b|n)[A-Z]")
BOOL_PREFIXES = ("is_", "has_", "can_", "should_")
def looks_boolean(value):               # a comparison like m >= 80, or True/False
    return isinstance(value, ast.Compare) or type(getattr(value, "value", None)) is bool
def named_things(tree):                  # yields (name, line, value or None)
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            args, defaults = node.args.args, node.args.defaults
            padded = [None] * (len(args) - len(defaults)) + defaults
            yield from ((arg.arg, arg.lineno, default) for arg, default in zip(args, padded))
        elif isinstance(node, ast.Assign) and isinstance(node.targets[0], ast.Name):
            yield node.targets[0].id, node.lineno, node.value
tree = ast.parse(SOURCE)
loop_vars = {node.target.id for node in ast.walk(tree) if isinstance(node, ast.For)}
warnings = []
for name, line, value in named_things(tree):
    if len(name) == 1 and name not in loop_vars:
        warnings.append((line, name, "single-letter name (not a loop variable)"))
    if HUNGARIAN.match(name):
        warnings.append((line, name, "Hungarian-style type prefix"))
    if value is not None and looks_boolean(value) and not name.startswith(BOOL_PREFIXES):
        warnings.append((line, name, "boolean without is_/has_/can_ prefix"))
for line, name, why in sorted(warnings):
    print(f"line {line}: {name!r} - {why}")
print(f"{len(warnings)} warning(s)")

line 2: 'd' - single-letter name (not a loop variable)
line 2: 'flag' - boolean without is_/has_/can_ prefix
line 2: 'm' - single-letter name (not a loop variable)
line 3: 'strName' - Hungarian-style type prefix
line 4: 'ok' - boolean without is_/has_/can_ prefix
line 6: 't' - single-letter name (not a loop variable)
6 warning(s)

৩ · Function — এক কাজ, এক স্তর, কম parameter

Function হলো কোডের বাক্য: একটি ভালো function একটি কাজ করে। “একটি কাজ” চেনার পরীক্ষা: ভেতরের প্রতিটি লাইন যদি নামের ঠিক এক ধাপ নিচের কথা বলে, তবে সেটি একটি কাজ। এটিই এক স্তরের abstraction (one level of abstraction per function). “রসিদ ছাপানো” আর “৩২টি ড্যাশের লাইন আঁকা” এক function-এ থাকলে পাঠককে স্তরের মধ্যে ওঠানামা করতে হয়। এটি SRP থেকে আলাদা কথা: SRP প্রশ্ন করে কোন মানুষ বা দল-এর কারণে module বদলায় (পর্ব ২৭, single responsibility), আর এখানে প্রশ্ন হলো একটি function পড়তে কতটা সহজ।

এক স্তরে আনার প্রধান হাতিয়ার extract function — কয়েকটি লাইন তুলে নিয়ে একটি নাম-ওয়ালা নতুন function বানানো, আর আগের জায়গায় সেই নাম ডাকা। Fowler-এর Refactoring (২য় সংস্করণ ২০১৮) বইয়ের সবচেয়ে বেশি ব্যবহৃত refactoring-গুলোর একটি এটি। নিচের stepper-এ কোচিং সেন্টারের ভর্তির রসিদ ছাপার function ধাপে ধাপে এক স্তরে আসছে।

def print_admission_slip(student):
    if not re.fullmatch(r"01[3-9]\d{8}", student["phone"]):
        raise ValueError(f"invalid phone: {student['phone']!r}")
    fee = student["months"] * 1500
    if student["marks"] >= 80:
        fee -= fee * 0.10
    line = "-" * 32
    print(line)
    print(student["name"].title().ljust(20) + f"{fee:>10.0f}")
    print(line)

def print_admission_slip(student):
    if not re.fullmatch(...):          # ক: phone যাচাই
        raise ValueError(...)
    fee = student["months"] * 1500       # খ: ফি হিসাব
    if student["marks"] >= 80:
        fee -= fee * 0.10
    line = "-" * 32                     # গ: অক্ষর সাজানো
    print(line) ... print(line)

def print_admission_slip(student):
    require_valid_phone(student["phone"])
    fee = student["months"] * 1500
    if student["marks"] >= 80:
        fee -= fee * 0.10
    line = "-" * 32
    print(line)
    print(student["name"].title().ljust(20) + f"{fee:>10.0f}")
    print(line)

def print_admission_slip(student):
    require_valid_phone(student["phone"])
    fee = tuition_fee(student["months"], student["marks"])
    line = "-" * 32
    print(line)
    print(student["name"].title().ljust(20) + f"{fee:>10.0f}")
    print(line)

def print_admission_slip(student):
    require_valid_phone(student["phone"])
    fee = tuition_fee(student["months"], student["marks"])
    print(format_slip(student["name"], fee))

def require_valid_phone(phone): ...      # নিচে, ব্যবহারের ক্রমে
def tuition_fee(months, exam_marks): ...
def format_slip(name, fee): ...          # লেখা ফেরত দেয়, ছাপে না

Parameter — যত কম, তত ভালো; আর flag argument নয়

প্রতিটি parameter পাঠকের মাথায় একটি বাড়তি জিনিস। দুটি পর্যন্ত সহজ; তিনটিতে ক্রম মনে রাখা কঠিন হয়; চার-পাঁচটি সাধারণত বোঝায় কয়েকটি মিলে একটি ধারণা — তখন একটি object বা dataclass-এ জুড়ে দিন (Enrollment(months, exam_marks, mode)), অথবা Python-এ keyword argument বাধ্যতামূলক করুন (def course_fee(*, months, exam_marks, mode)), যাতে call site-এ নাম লিখতেই হয়।

সবচেয়ে খারাপ parameter হলো flag argument — একটি boolean, যা function-কে দুই রকম কাজ করতে বলে। render(report, True) পড়ে কেউ বলতে পারেন না True মানে কী। আর ঘোষণাতেই স্বীকার করা হলো যে function একাধিক কাজ করে: “flag সত্য হলে এটা, মিথ্যা হলে ওটা”। প্রতিকার: দুটি function (render_pdf, render_html), একটি Enum (render(report, Format.PDF)), অথবা অন্তত keyword argument (as_pdf=True) — Fowler-এর ক্যাটালগে “Remove Flag Argument”.

লুকানো side effect আর command–query separation

পর্ব ২৬-এ (নকশার নীতি) command–query separation দেখেছেন: method হয় অবস্থা বদলাবে, নয়তো প্রশ্নের উত্তর দেবে। Clean code-এর দিক থেকে এর সবচেয়ে বড় শত্রু হলো নামে লুকানো side effect. is_valid_pin(pin) নাম শুনে সবাই ধরে নেন এটি শুধু হ্যাঁ/না বলবে; ভেতরে এটি চেষ্টাও গুনলে log-এ একবার ডাকলেই আচরণ বদলাবে (অনুশীলন ১)। নিয়ম: নাম যা বলে, function ঠিক তা-ই করবে।

এবার সব মিলিয়ে: একটি পুরোনো ফি-হিসাবের function (অস্পষ্ট নাম, flag argument, nested if, নামহীন সংখ্যা) আর তার পরিষ্কার রূপ, পাঁচটি ইনপুটে পাশাপাশি — refactoring মানে আচরণ একই রেখে গঠন বদলানো।

# Fictional coaching-centre course fee. BEFORE: unclear names, a flag
# argument, nested ifs and magic numbers. AFTER: the same rules, cleaned.
def calc(d, m, f):
    t = 0
    if d > 0:
        if f:
            t = d * 1200
            if m >= 80:
                t = t - t * 0.15
        else:
            t = d * 1500
            if m >= 80:
                t = t - t * 0.10
        if d > 6:
            t = t - 500
    return round(t)
MONTHLY_FEE_TK = {"online": 1200, "offline": 1500}
MERIT_DISCOUNT = {"online": 0.15, "offline": 0.10}
MERIT_MIN_MARKS, LONG_COURSE_MONTHS, LONG_COURSE_REBATE_TK = 80, 6, 500

def course_fee(months, exam_marks, mode):
    if months <= 0:
        return 0
    fee = months * MONTHLY_FEE_TK[mode]
    if exam_marks >= MERIT_MIN_MARKS:
        fee -= fee * MERIT_DISCOUNT[mode]
    if months > LONG_COURSE_MONTHS:
        fee -= LONG_COURSE_REBATE_TK
    return round(fee)
CASES = [(3, 70, True), (3, 85, False), (12, 90, True), (0, 95, False), (8, 60, False)]
for months, marks, online in CASES:
    mode = "online" if online else "offline"
    old, new = calc(months, marks, online), course_fee(months, marks, mode)
    print(f"{months:>2} mo, {marks} marks, {mode:<7}: old {old:>5}, new {new:>5}",
          "same" if old == new else "DIFFERENT")

 3 mo, 70 marks, online : old  3600, new  3600 same
 3 mo, 85 marks, offline: old  4050, new  4050 same
12 mo, 90 marks, online : old 11740, new 11740 same
 0 mo, 95 marks, offline: old     0, new     0 same
 8 mo, 60 marks, offline: old 11500, new 11500 same

৪ · Nesting কমানো — guard clause আর early return

একটি if-এর ভেতরে আরেকটি if, তার ভেতরে আরেকটি — কোড ক্রমশ ডানে সরে যায়, পাশ থেকে দেখতে তীরের মাথার মতো। একে প্রায়ই বলা হয় arrow code. কতগুলো ব্লক একটির ভেতরে আরেকটি আছে, তার মাপ হলো nesting depth. Depth যত বেশি, পাঠককে তত বেশি শর্ত একসাথে মাথায় রাখতে হয়, আর else তার if থেকে দূরে সরে যায়।

সমাধান হলো guard clause: যে অবস্থায় কাজ করা যাবে না, function-এর শুরুতেই সেটা যাচাই করে বেরিয়ে যান (early return). সব পাহারা পার হলে বাকি কোড মূল কাজ — happy path — সোজা বাঁ দিক ঘেঁষে লেখা থাকে। Fowler-এর ক্যাটালগে এর নাম “Replace Nested Conditional with Guard Clauses”.

নিচের প্রোগ্রামে ঠিক এই দুটি রূপ। একটি ছোট function নিজের source লেখা পড়ে { আর } গুনে nesting depth মাপে, আর পাঁচটি অনুরোধে দুটি রূপের উত্তর মিলিয়ে দেখে।

// Same refund rules, two shapes. Fictional coaching centre.
function refundNested(req) {
  if (req) {
    if (req.paid) {
      if (req.days <= 7) {
        if (req.classes < 3) {
          return "full refund";
        } else return "rejected: attended " + req.classes + " classes";
      } else return "rejected: asked after 7 days";
    } else return "rejected: nothing paid";
  } else return "rejected: no request";
}
function refundGuarded(req) {
  if (!req) return "rejected: no request";
  if (!req.paid) return "rejected: nothing paid";
  if (req.days > 7) return "rejected: asked after 7 days";
  if (req.classes >= 3) return "rejected: attended " + req.classes + " classes";
  return "full refund";
}
function nestingDepth(fn) {            // deepest { } block inside the body
  let depth = 0, deepest = 0;
  for (const ch of fn.toString()) {
    if (ch === "{") deepest = Math.max(deepest, ++depth);
    if (ch === "}") depth--;
  }
  return deepest - 1;                  // the body's own { } does not count
}
const requests = [null, { paid: false, days: 1, classes: 0 },
  { paid: true, days: 10, classes: 0 }, { paid: true, days: 3, classes: 5 },
  { paid: true, days: 2, classes: 1 }];
for (const r of requests)
  console.log((refundNested(r) === refundGuarded(r) ? "same  " : "DIFF  ") + refundGuarded(r));
for (const fn of [refundNested, refundGuarded])
  console.log(`${fn.name}: depth ${nestingDepth(fn)}, ${fn.toString().split("\n").length} lines`);

same  rejected: no request
same  rejected: nothing paid
same  rejected: asked after 7 days
same  rejected: attended 5 classes
same  full refund
refundNested: depth 4, 11 lines
refundGuarded: depth 0, 7 lines

এক লাফে পুরো কাঠামো বদলানো ঝুঁকিপূর্ণ। নিচের stepper-এ একই refactoring ছোট ধাপে — প্রতি ধাপে একটি স্তর সরে, আর প্রতি ধাপে একই পাঁচটি অনুরোধে test চলে।

if (req) {
  if (req.paid) {
    if (req.days <= 7) {
      if (req.classes < 3) {
        return "full refund";
      } else return "rejected: attended …";
    } else return "rejected: asked after 7 days";
  } else return "rejected: nothing paid";
} else return "rejected: no request";

if (!req) return "rejected: no request";
if (req.paid) {
  if (req.days <= 7) {
    if (req.classes < 3) {
      return "full refund";
    } else return "rejected: attended …";
  } else return "rejected: asked after 7 days";
} else return "rejected: nothing paid";

if (!req) return "rejected: no request";
if (!req.paid) return "rejected: nothing paid";
if (req.days <= 7) {
  if (req.classes < 3) {
    return "full refund";
  } else return "rejected: attended …";
} else return "rejected: asked after 7 days";

if (!req) return "rejected: no request";
if (!req.paid) return "rejected: nothing paid";
if (req.days > 7) return "rejected: asked after 7 days";
if (req.classes < 3) {
  return "full refund";
} else return "rejected: attended …";

if (!req) return "rejected: no request";
if (!req.paid) return "rejected: nothing paid";
if (req.days > 7) return "rejected: asked after 7 days";
if (req.classes >= 3) return "rejected: attended …";
return "full refund";

৫ · Comment — কোড বলে “কী”, comment বলে “কেন”

Martin Clean Code-এ প্রায় এভাবে লেখেন: comment হলো কোডে নিজের কথা প্রকাশ করতে না পারার ক্ষতিপূরণ। Ousterhout-এর মতো অন্যরা বলেন, কোড কখনো সব বলতে পারে না — কেন এই সিদ্ধান্ত, interface-এর প্রতিশ্রুতি কী — এগুলো লেখাই নকশার অংশ। দুই মতের সাধারণ ভিত্তি: যে comment কোডের কথা আবার বলে, সেটি অপ্রয়োজনীয়; যে comment কোডে যা বলা যায় না তা বলে, সেটি মূল্যবান।

শেষ সারিটি মনে রাখুন: compiler আর test comment যাচাই করে না, তাই কোড বদলায়, comment পড়ে থাকে, একদিন মিথ্যা বলে।

Docstring আর JSDoc — interface-এর লিখিত প্রতিশ্রুতি

একটি ব্যতিক্রম আছে যেখানে প্রায় সবাই একমত: public function, class আর module-এর documentation. Python-এ এটি docstring — function-এর প্রথম লাইনে একটি string, যা help() আর editor দেখায় (রীতিনীতি PEP 257-এ)। JavaScript-এ প্রচলিত রূপ JSDoc — /** … */ comment, যা editor আর TypeScript-এর type-checker-ও পড়তে পারে। এগুলো “কীভাবে” নয়, “কী প্রতিশ্রুতি” বলে: কী নেয়, কী ফেরত দেয়, কখন কোন error তোলে — অর্থাৎ পর্ব ৩১-এর (interface আর contract) contract-এর মানুষের-পড়ার-মতো রূপ।

def course_fee(months: int, exam_marks: int, mode: str) -> int:
    """Return the total course fee in taka, rounded to whole taka.

    Merit discount applies at 80 marks or more; courses longer than
    6 months get a one-time 500 tk rebate. Raises KeyError for an
    unknown mode ("online" and "offline" are valid).

    >>> course_fee(3, 85, "offline")
    4050
    """

/**
 * Decide a refund request (fictional coaching centre).
 * @param {{paid: boolean, days: number, classes: number} | null} req
 * @returns {string} "full refund" or a reason starting with "rejected:"
 */
function refundGuarded(req) { /* … */ }

Docstring-এর >>> লাইনগুলো শুধু উদাহরণ নয় — Python-এর doctest module এগুলো চালিয়ে মিলিয়ে দেখতে পারে। অর্থাৎ documentation-এর একটি অংশ মিথ্যা হলে test লাল হয়। Comment-কে সত্য রাখার এটিই সবচেয়ে ভালো উপায়: যতটা সম্ভব comment-কে যাচাইযোগ্য করা — type hint, doctest, assertion.

TODO-র নিয়ম

TODO comment (# TODO: …) হলো ভবিষ্যতের কাজের চিরকুট। সমস্যা হলো, চিরকুট জমতে জমতে কোড-ভিত্তিতে শত শত TODO পড়ে থাকে, যার মালিক নেই, তারিখ নেই, আর কেউ জানে না এখনো প্রাসঙ্গিক কি না — এটি নীরব technical debt (পর্ব ৪৩, technical debt আর legacy code). অভ্যাস: TODO-তে issue নম্বর বা মালিক রাখুন (# TODO(#142): …), নিয়মিত তালিকা দেখুন, আর যে TODO কখনো হবে না তা মুছুন। অনেক দল linter দিয়ে issue নম্বর ছাড়া TODO আটকায়।

Commented-out কোড — Git মনে রাখে

“পরে লাগতে পারে” ভেবে কোড # দিয়ে ঢেকে রাখা খুব সাধারণ। ক্ষতিটা নীরব: পরের পাঠক জানেন না এটি কেন আছে, ভয়ে কেউ মোছেন না, search-এ আসল কোডের সাথে মিশে আসে, আর চারপাশ বদলে যাওয়ায় uncomment করলে চলেও না। পুরোনো কোড রাখার আসল জায়গা হলো version control. পর্ব ৯-এ (history আর পার্থক্য দেখা) log আর show দেখেছেন; এখানে একটি নতুন option: git log -S "লেখা", যা দেখায় কোন commit-এ ওই লেখাটি যোগ হয়েছে বা মুছেছে (একে বলে pickaxe খোঁজ; বিস্তারিত পর্ব ৫৫-এ)। নিচে একটি কাল্পনিক repository-তে পুরোনো ঈদ-অফারের commented-out কোড প্রথমে রাখা, তারপর মুছে ফেলা, আর শেষে খুঁজে বের করা হয়েছে:

$ git log --oneline
6851b01 refactor: remove commented-out Eid offer
314837b chore: park the old Eid offer
8fd7f26 feat: add merit discount
$ git log -S "old_eid_offer" --oneline
6851b01 refactor: remove commented-out Eid offer
314837b chore: park the old Eid offer
$ git show 314837b:fee.py
MERIT_DISCOUNT = 0.10

def merit_discount(fee, exam_marks):
    # old_eid_offer: Eid offer, keep just in case
    # if exam_marks >= 70:
    #     return fee * 0.20
    return fee * MERIT_DISCOUNT if exam_marks >= 80 else 0

৬ · Formatting — তর্ক নয়, স্বয়ংক্রিয় formatter

Formatting মানে কোডের চেহারা: indentation, space, বন্ধনী, লাইনের দৈর্ঘ্য। আচরণে প্রভাব নেই (Python-এর indentation বাদে), কিন্তু পড়ার গতিতে বিশাল প্রভাব — আর ভিন্ন হাতের ছাপে প্রতিটি diff-এ space-এর বদল মিশে যায়।

Code formatter এমন tool, যা কোড পড়ে একটি নির্দিষ্ট নিয়মে আবার লিখে দেয় — আচরণ না বদলে। Style guide হলো মানুষের জন্য লেখা নিয়ম; formatter সেই নিয়মের যে অংশ যন্ত্রে প্রয়োগ করা যায়, তা করে ফেলে।

Go সম্প্রদায়ের একটি প্রচলিত প্রবাদ (সাধারণত Rob Pike-এর নামে) এই ধারণার সারকথা: gofmt-এর style কারও প্রিয় নয়, তবু gofmt সবার প্রিয়। কারণ formatter-এর আসল লাভ সুন্দর চেহারা নয় — তর্ক শেষ হওয়া. Review-তে space নিয়ে সময় নষ্ট হয় না, diff-এ শুধু আসল পরিবর্তন থাকে। Formatter save-এর সময় চলুক, আর CI-তেও (পর্ব ৫৮) যাচাই হোক।

Formatter যা পারে না — লাইন-দৈর্ঘ্য আর উল্লম্ব খোলামেলা ভাব

• লাইনের দৈর্ঘ্য: PEP 8 ৭৯ অক্ষর বলে, Black ৮৮, অনেক দল ১০০ বা ১২০. একটি সংখ্যা বেছে সবাই মানাই আসল; খুব লম্বা লাইন প্রায়ই বোঝায় লাইনটি বেশি কাজ করছে।
• উল্লম্ব খোলামেলা ভাব (vertical openness): একটি ধারণা শেষ হলে একটি ফাঁকা লাইন — অনুচ্ছেদের মতো। যাচাই, হিসাব, ফল ছাপা — তিনটি অংশ তিনটি “অনুচ্ছেদ”।
• উল্লম্ব ঘনত্ব: যে লাইনগুলো একসাথে কাজ করে, সেগুলো কাছাকাছি; variable ঘোষণা করুন যেখানে প্রথম লাগে, file-এর মাথায় সব জমিয়ে নয়। সম্পর্কিত function কাছাকাছি, ডাকার ক্রমে (stepdown rule, §৩)।
• File-এর আকার: একটি file একটি বিষয়। কয়েক হাজার লাইনের file প্রায় সবসময় কয়েকটি আলাদা ধারণা একসাথে বহন করে (§৮)।

৭ · Magic number আর error handling-এর লেখার ধরন

Magic number — নামহীন সংখ্যা

কোডের মাঝখানে হঠাৎ 1500, 0.10, 7 — এগুলোকে বলে magic number: সংখ্যাটি কেন এখানে, কী বোঝায়, তা কোথাও লেখা নেই। পাঠক জানেন না 7 মানে সাত দিন না সাতটি ক্লাস, আর নিয়ম বদলালে সংখ্যাটি খুঁজে বেড়াতে হয়। প্রতিকার হলো named constant: REFUND_WINDOW_DAYS = 7. সব সংখ্যা constant হবে না — 0, 1, শতাংশের 100, বা len(items) - 1-এর 1 নিজেই স্পষ্ট। প্রশ্ন একটাই: অন্য কেউ সংখ্যাটি দেখে কি এর অর্থ আর উৎস বলতে পারবেন? ESLint-এ no-magic-numbers নামে একটি নিয়ম আছে, যা চালু করলে এমন সংখ্যা ধরে।

নিচের প্রোগ্রামটি একটি বাস্তব ধাঁচের ভুল দেখায়। কোচিং সেন্টারের বোর্ড সিদ্ধান্ত নিল, দেরিতে ফি দেওয়ার জরিমানা ৫০০ থেকে কমে ৩০০ টাকা হবে। তাড়াহুড়োয় একজন developer পুরোনো কোডে find-and-replace দিয়ে সব “500” বদলে “300” করলেন। (প্রোগ্রামে eval শুধু “কোডের লেখা বদলানো” দেখানোর জন্য; বাস্তব কোডে eval এড়িয়ে চলুন।)

// Magic numbers vs named constants. Fictional coaching centre.
// Policy change: the late-payment fine drops from 500 tk to 300 tk.
const magicSource = `(months, daysLate) => {
  let fee = months * 1500;
  if (months > 6) fee -= 500;
  if (daysLate > 10) fee += 500;
  return fee;
}`;
// A hurried edit: find-and-replace every "500" with "300".
const hits = magicSource.split("500").length - 1;
const magicV1 = eval(magicSource);
const magicV2 = eval(magicSource.replaceAll("500", "300"));

// Named constants: each number has ONE name and ONE meaning.
const RULES_V1 = Object.freeze({
  MONTHLY_FEE_TK: 1500, LONG_COURSE_MONTHS: 6, LONG_COURSE_REBATE_TK: 500,
  LATE_AFTER_DAYS: 10, LATE_FINE_TK: 500,
});
const RULES_V2 = Object.freeze({ ...RULES_V1, LATE_FINE_TK: 300 }); // the one edit
const makeInvoice = (r) => (months, daysLate) => {
  let fee = months * r.MONTHLY_FEE_TK;
  if (months > r.LONG_COURSE_MONTHS) fee -= r.LONG_COURSE_REBATE_TK;
  if (daysLate > r.LATE_AFTER_DAYS) fee += r.LATE_FINE_TK;
  return fee;
};
const namedV1 = makeInvoice(RULES_V1), namedV2 = makeInvoice(RULES_V2);

console.log('"500" appears ' + hits + " times in the magic version");
for (const [m, late] of [[8, 15], [3, 0], [8, 0]]) {
  console.log(`${m} months, ${late} days late: magic ${magicV1(m, late)} -> ${magicV2(m, late)}` +
              `, named ${namedV1(m, late)} -> ${namedV2(m, late)}`);
}

"500" appears 3 times in the magic version
8 months, 15 days late: magic 12000 -> 10400, named 12000 -> 11800
3 months, 0 days late: magic 4500 -> 3900, named 4500 -> 4500
8 months, 0 days late: magic 11500 -> 10100, named 11500 -> 11500

Error handling-এর লেখার ধরন

পর্ব ৩১-এ (interface আর contract) error জানানোর তিন পথ আর পাঁচটি নিয়ম দেখেছেন; সেগুলো আবার বলব না। এখানে প্রশ্নটি হলো: error সামলানোর কোড কীভাবে লিখলে মূল কাজ চাপা পড়ে না।

• Error handling নিজেই “একটি কাজ”: try-এর ভেতরে অল্প কোড, প্রায়ই একটি function-ডাক; পঞ্চাশ লাইনের try-ব্লকে কোন লাইন কোন error তোলে, কেউ বলতে পারেন না।
• প্রসঙ্গসহ exception: ValueError("invalid") নয়, FeeError(f"student {sid}: unknown mode {mode!r}"). নিচু স্তরের error ধরে উঁচু স্তরের অর্থ যোগ করলে মূল কারণ হারাবেন না — Python-এ raise FeeError(...) from e, JavaScript-এ new Error(msg, { cause: e }). Log-এ পাসওয়ার্ড বা পুরো phone নম্বর নয়।
• null ফেরত দেবেন না, null পাঠাবেন না: “কিছু নেই” বোঝাতে None/null ফেরত দিলে প্রতিটি caller-কে মনে করে যাচাই করতে হয়, আর একজন ভুললেই crash (null reference). Collection হলে খালি list ফেরত দিন; একক মান হলে স্পষ্ট exception, optional type, বা Null Object — পর্ব ৩১-এর §৮-এ বিস্তারিত।
• সীমানায় fail fast: বাইরে থেকে আসা মান (form, file, API) শুরুতেই guard দিয়ে যাচাই করুন (§৪)।
• স্বাভাবিক প্রবাহের জন্য exception নয়: loop থামাতে exception তুললে পাঠক ভাবেন কিছু ভুল হয়েছে।

# Before: the happy path is buried, the error loses its cause
def import_students(path):
    try:
        rows = open(path, encoding="utf-8").read().splitlines()
        students = [parse_student(row) for row in rows[1:]]
        save_all(students)
        send_summary_sms(len(students))
    except Exception:
        print("error")                      # what? where? why?

# After: one job per function, context kept, nothing swallowed
def import_students(path):
    students = read_students(path)          # raises ImportError with row number
    save_all(students)
    send_summary_sms(len(students))

def read_students(path):
    with open(path, encoding="utf-8") as file:
        rows = file.read().splitlines()[1:]
    try:
        return [parse_student(row) for row in rows]
    except ValueError as e:
        raise ImportError(f"{path}: bad student row ({e})") from e

প্রথম রূপে চারটি আলাদা কাজ এক try-এর ভেতরে, আর যেকোনো ব্যর্থতা — file নেই, একটি সারি ভুল, database বন্ধ, SMS যায়নি — একই অর্থহীন “error” ছাপে, তারপর চুপচাপ এগিয়ে যায় (swallowed exception). দ্বিতীয় রূপে মূল function তিন লাইনের সুখী পথ; যে error সামলানোর মতো কিছু করা যায় না (database বন্ধ), সেটি স্বাভাবিকভাবে ওপরে ওঠে; আর সারি পড়ার ভুল একটি নির্দিষ্ট error-এ বদলায়, file-এর নাম আর মূল কারণসহ। আরও দেখুন Python কোর্সের exception পর্বে, JavaScript-এ error handling পর্বে।

৮ · ছোট, সুসংগত module, Boy Scout rule আর নিয়মের সীমা

Function থেকে এক ধাপ ওপরে উঠলে একই নীতি module আর file-এ খাটে। পর্ব ২৫-এ (coupling আর cohesion) দেখেছেন, একটি module-এর ভেতরের জিনিসগুলো একই কাজে লাগলে cohesion বেশি। Clean code-এর ভাষায়: একটি module-এর নাম পড়ে বলা যাবে ভেতরে কী আছে, আর ভেতরের সব কিছু সেই নামের সাথে মানায়। utils.py ধরনের নাম প্রায়ই আবর্জনার ঝুড়ি হয়ে ওঠে। আর সুসংগতি ব্যক্তিগত পছন্দের চেয়ে গুরুত্বপূর্ণ: একই সমস্যা সবখানে একই উপায়ে সমাধান হলে একটি অংশ বুঝলে বাকিগুলোও বোঝা যায়; অন্যের file-এ সেই file-এর রীতি মানুন।

Boy Scout rule

Martin Clean Code-এ আর 97 Things Every Programmer Should Know (২০১০) সংকলনে তাঁর একটি ছোট লেখায় স্কাউটদের একটি নিয়ম ধার করেন: ক্যাম্পের জায়গা যেমন পেয়েছিলেন, তার চেয়ে একটু পরিষ্কার করে রেখে যান। এই Boy Scout rule-এর কোডের রূপ: যে কোডে কাজ করতে ঢুকেছেন, বেরোনোর সময় সেটি একটু ভালো রেখে যান — একটি অস্পষ্ট নাম বদলানো, একটি magic number-কে নাম দেওয়া, একটি পুরোনো comment মোছা।

তিনটি সাবধানতা: (১) পরিধির মধ্যে — ছুঁয়ে যাওয়া function, পুরো module নয়; (২) আলাদা commit-এ — “rename: d → months” আর “feat: online fee” দুটি আলাদা atomic commit; (৩) test-এর পাহারায়. পরিকল্পিত বড় refactoring পর্ব ৪২-এর (code smell আর refactoring) বিষয়, জমা কোড-ঋণ পর্ব ৪৩-এর।

নিয়ম যখন একে অপরের বিরুদ্ধে

Clean code-এর নিয়মগুলো সবসময় একই দিকে টানে না। কয়েকটি পরিচিত টানাপোড়েন:

সবচেয়ে আলোচিত টানাপোড়েনটি প্রথমটি। Ousterhout-এর deep module-এর ধারণা বলে, একটি module বা function-এর মূল্য তার interface-এর জটিলতার তুলনায় সে কতটা কাজ লুকায় (পর্ব ২৫-এও ধারণাটি দেখেছেন)। খুব ছোট টুকরো করলে প্রতিটি টুকরোর interface (নাম, parameter, কী ফেরত দেয়) প্রায় তার কাজের সমান বড় হয়ে যায় — একে তিনি বলেন shallow module. তাঁর মতে এতে মোট জটিলতা কমে না, শুধু ছড়িয়ে পড়ে। Martin-এর উত্তর: ভালো নামের ছোট function-এর ভেতরে ঢুকতেই হয় না। দুই পক্ষের লক্ষ্য একই — পাঠকের চাপ কমানো। একটি ব্যবহারিক পরীক্ষা: নতুন function-এর নাম কি তার ভেতরের কোডের চেয়ে সহজে বোঝা যায়? হ্যাঁ হলে বের করুন; না হলে, যেমন add_one(x) যা x + 1 ফেরত দেয়, তবে বের করবেন না।

৯ · AI-এর যুগে clean code

AI দ্রুত দেখতে-পরিষ্কার কোড লেখে, কিন্তু নাম ভুল জিনিস বোঝাতে পারে, comment কোডের সাথে না মিলতে পারে, আর “refactor” আচরণ বদলাতে পারে। Clean code-এর মাপকাঠি তাই AI-এর লেখা যাচাইয়ের চশমা।

AI-এর পরিষ্কার-করা কোড হাতে পেলে — যাচাইয়ের চেকলিস্ট

• বদলের আগে আর পরে একই test চালিয়েছি; সীমার মান আর প্রতিটি শাখা test-এ আছে
• প্রতিটি নতুন নাম পড়ে অনুমান করেছি function কী করে, আর কোড পড়ে অনুমানটি মিলেছে; কোনো লুকানো side effect নেই
• প্রতিটি comment “কেন” বলে বা interface-এর প্রতিশ্রুতি দেয়; কোডের সাথে কোনো comment সাংঘর্ষিক নয়
• উদ্ধৃত নিয়ম, বই আর tool-option মূল নথিতে মিলিয়েছি; কোনো history-বদলানো Git command চালানোর আগে throwaway clone-এ পরীক্ষা করেছি
• Code-এর উৎস আর license নিয়ে সন্দেহ থাকলে দলকে জানিয়েছি; prompt-এ কোনো secret দিইনি