میرے بہترین طریقے – عمومی

1. کمنٹس – زحمت بھی، رحمت بھی

اچھے کمنٹس لکھنا ایک فن ہے۔ سوچ سمجھ کر لکھے جائیں تو نعمت، ورنہ اکثر بے کار۔

سیلف ڈاکیومنٹنگ کوڈ کا مطلب “کوئی کمنٹ نہیں” نہیں ہے۔ کوڈ کو جہاں تک ممکن ہو خود کیسے کو بیان کرنا چاہیے؛ کمنٹس کیوں، غیر واضح حدود و شرائط اور کسی API کے کنٹریکٹ کی وضاحت کرتے ہیں۔

ذیل میں سیلف ڈاکیومنٹنگ کوڈ کی کچھ مثالیں ہیں، اور ساتھ ہی اچھے اور برے کمنٹس کی بھی۔

ایک عام دلیل یہ ہے کہ کمنٹس جلد پرانے ہو جاتے ہیں۔ حقیقت یہ ہے کہ یہ مسئلہ ویری ایبلز اور میتھڈز کے ناموں پر بھی اتنا ہی لاگو ہوتا ہے!

اُف – یہ کبھی نہ کریں:

int age = 32; // set the value of the age integer to 32

سیلف ڈاکیومنٹنگ: ویری ایبلز کے بامعنی نام آدھی جنگ جیت لیتے ہیں

برا:

var dateTime = DateTimeUtil.getNow();

اچھا:

var now = DateTimeUtil.getNow();

ایک اور مثال:

برا:

User user = this.getBruce();

برا:

// testing user without permission
User user = this.getBruce();

اچھا:

User userWithoutPermission = this.getBruce();

سیلف ڈاکیومنٹنگ: میتھڈز کے بامعنی نام

برا:

public String sanitizeInput(String input) {
    // replace underscore with spaces
    return input.replaceAll("_", " ");
}

اچھا:

public String replaceUnderscoreWithSpaces(String input) {
    return input.replaceAll("_", " ");
}

سیلف ڈاکیومنٹنگ: پرائیویٹ میتھڈز

برا: یہ میتھڈ قاری کو مجبور کرتا ہے کہ وہ ویلیڈیشن، حساب اور کاروباری اصول کو بیک وقت سمجھے۔

public Invoice createInvoice(Order order, Customer customer) {
    if (order.items().isEmpty()) {
        throw new IllegalArgumentException("Order needs at least one item");
    }

    BigDecimal subtotal = order.items().stream()
            .map(item -> item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    BigDecimal discount = customer.isPremium()
            ? subtotal.multiply(new BigDecimal("0.10"))
            : BigDecimal.ZERO;

    return new Invoice(order.id(), subtotal, discount, subtotal.subtract(discount));
}

اچھا: پبلک میتھڈ عمل کی کہانی سناتا ہے۔ پرائیویٹ، اسٹیٹ لیس (stateless) میتھڈز ہر ارادے کو الگ نام دیتے ہیں اور اپنی ڈیپنڈنسیز کو پیرامیٹرز اور ریٹرن ویلیوز کے ذریعے واضح کرتے ہیں۔

public Invoice createInvoice(Order order, Customer customer) {
    requireItems(order);
    BigDecimal subtotal = calculateSubtotal(order.items());
    BigDecimal discount = loyaltyDiscountFor(customer, subtotal);

    return invoiceFor(order, subtotal, discount);
}

private static void requireItems(Order order) {
    if (order.items().isEmpty()) {
        throw new IllegalArgumentException("Order needs at least one item");
    }
}

private static BigDecimal calculateSubtotal(List<OrderItem> items) {
    return items.stream()
            .map(item -> item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
}

private static BigDecimal loyaltyDiscountFor(Customer customer, BigDecimal subtotal) {
    return customer.isPremium()
            ? subtotal.multiply(new BigDecimal("0.10"))
            : BigDecimal.ZERO;
}

private static Invoice invoiceFor(
        Order order,
        BigDecimal subtotal,
        BigDecimal discount
) {
    return new Invoice(order.id(), subtotal, discount, subtotal.subtract(discount));
}

ہر سطر کو اپنا الگ میتھڈ نہیں چاہیے۔ الگ وہ مربوط خیال کیا جاتا ہے جسے درست طور پر نام دیا جا سکے۔ اس کے برعکس processData() یا handleStuff() جیسے ناموں سے کچھ حاصل نہیں ہوتا۔

عام اصول: کمنٹ میں لکھیں کہ کچھ کیوں ہوتا ہے، یہ نہیں کہ کیا ہوتا ہے

یہ واضح ہے کہ یہاں کیا ہو رہا ہے:

public Duration retryDelay(int retryCount) {
    long seconds = Math.min(1L << retryCount, 60);
    return Duration.ofSeconds(seconds);
}

لیکن یہ کیوں ہو رہا ہے؟

بہتر:

public Duration retryDelay(int retryCount) {
    // Cap the delay so an outage never blocks queued jobs for more than one minute.
    long seconds = Math.min(1L << retryCount, 60);
    return Duration.ofSeconds(seconds);
}

ایک اور حقیقی مثال۔ یہاں Ajax لوڈنگ اسپنر کو دکھانے اور چھپانے کے میتھڈز ہیں۔ لیکن میتھڈز چار ہیں۔ کیوں، یہ پہلی نظر میں پوری طرح واضح نہیں:

function showAjaxLoader() {
    $('.layout-ajax-loader').children().first().show();
}

function hideAjaxLoader() {
    $('.layout-ajax-loader').children().first().hide();
}

function suppressAjaxLoader() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = 'none';
}

function releaseAjaxLoader() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = '';
}

تمام میتھڈز بہت ملتے جلتے لگتے ہیں اور کسی نہ کسی طرح CSS کے ذریعے نظر آنے کو بدلتے ہیں۔ ایک مختصر کمنٹ سے استعمال کی صورتیں فوراً واضح ہو جاتی ہیں:

showAjaxLoader: function() {
    $('.layout-ajax-loader').children().first().show();
},

hideAjaxLoader: function() {
    $('.layout-ajax-loader').children().first().hide();
},

// take the control from primefaces and don't allow the spinner to show, no matter what
suppressAjaxLoader: function() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = 'none';
},

// reset the state after hiding, to give the control back to primefaces
releaseAjaxLoader: function() {
    getOnlyElementByClassOrNull('layout-ajax-loader').style.display = '';
},

ایک اور مثال:

برا:

/**
 * Sets the tool tip text.
 *
 * @param text  the text of the tool tip
 */
public void setToolTipText(String text) {}

اچھا:

/**
 * Registers the text to display in a tool tip. The text
 * displays when the cursor lingers over the component.
 *
 * @param text  the string to display. If the text is null,
 *              the tool tip is turned off for this component.
 */
public void setToolTipText(String text) {}

21 جون 2021 کی ورکشاپ میں بحث: تمام ڈویلپرز کی متفقہ رائے تھی کہ Javadoc سے عموماً بچنا چاہیے (پیرامیٹرز کا ڈراؤنا خواب، ہمیشہ پرانا اور سنبھالنے میں ناگوار) اور اسے صرف تب استعمال کیا جائے جب کسی پیرامیٹر کو واقعی مزید وضاحت کی ضرورت ہو، یا بصورتِ دیگر پورا لمبا میتھڈ پڑھنا پڑے۔

عام اصول سے استثنا: کمنٹ میں لکھیں کہ کیا ہوتا ہے – یہاں یہ مناسب ہے

جب اس سے پڑھنا نمایاں طور پر آسان ہو جائے، کیونکہ ورنہ کوڈ واضح نہیں:

let isAlwaysAllowedKey = (
    e.which === 8  || /* BACKSPACE */
    e.which === 35 || /* END */
    e.which === 36 || /* HOME */
    e.which === 37 || /* LEFT */
    e.which === 38 || /* UP */
    e.which === 39 || /* RIGHT*/
    e.which === 40 || /* DOWN */
    e.which === 46 || /* DEL*/
    e.ctrlKey === true && e.which === 65 || /* CTRL + A */
    e.ctrlKey === true && e.which === 88 || /* CTRL + X */
    e.ctrlKey === true && e.which === 67 || /* CTRL + C */
    e.ctrlKey === true && e.which === 90   /* CTRL + Z */
)

کمنٹس – Linux کرنل کے کوڈ میں گالیاں

آخر میں Linux کرنل سے ایک مزے دار قصہ – سورس کوڈ میں تمام گالیوں کی تعداد:

https://www.vidarholen.net/contents/wordcount/#fuck*,shit*,damn*,idiot*,retard*

کمنٹس لکھنے کا لطف اٹھائیں!

2. بڑے پروگرام روٹینز میں پرائیویٹ میتھڈز خطرناک ہیں

خبردار! آج کی آبجیکٹ اورینٹڈ دنیا میں ہمیشہ بہت سے پرائیویٹ میتھڈز ہوتے ہیں۔ عام طور پر یہ کوئی مسئلہ نہیں۔ مسئلہ تب بنتا ہے جب یہ میتھڈز فیلڈز تک، یعنی اسٹیٹ (State) تک، رسائی کریں اور بڑی روٹینز کے اندر ہوں۔ ایسے ذیلی میتھڈز پرائیویٹ اور اسٹیٹ لیس ہونے چاہییں۔ ورنہ ان کا نقصان یہ ہے کہ اکیلے کال کیے جانے پر یہ اکثر مصیبت کھڑی کر دیتے ہیں۔ ڈویلپرز کو ذیلی میتھڈ کو براہِ راست کال کرنے کا خیال آئے گا۔ غیر درست اسٹیٹس بگز کی بڑی وجوہات میں سے ایک ہیں۔ اس بارے میں ایک دلچسپ مضمون، جو John Carmack (id Software، Doom) کے کچھ بیانات پر ہے، اور اس بارے میں کہ جن ایپلیکیشنز میں کوڈ کا انتہائی مستحکم ہونا ضروری ہے (مثلاً خلائی پرواز)، وہاں ذیلی روٹینز اکثر ممنوع ہوتی ہیں، جس سے کوڈ زیادہ متعین (deterministic) ہو جاتا ہے: http://number-none.com/blow/john_carmack_on_inlined_code.html

یہ قصہ جدید اسٹیٹ لیس Java/Spring دنیا پر صرف جزوی طور پر لاگو ہوتا ہے، لیکن پھر بھی سوچنے کے لیے اچھا نکتہ ہے۔