Greppability एक कम आंका गया code metric है

(morizbuesing.com)

22 पॉइंट द्वारा GN⁺ 2024-09-04 | 5 टिप्पणियां | WhatsApp पर शेयर करें

किसी अनजान codebase का maintenance करते समय strings को search करने में बहुत समय खर्च होता है
अपने अकेले बनाए गए project में भी function names, error messages, class names आदि बहुत-सी चीज़ें search करनी पड़ती हैं
अगर search ठीक से न हो, तो codebase में references न मिलने के कारण किसी चीज़ को अनावश्यक समझ लेने का जोखिम होता है
ऐसी स्थिति में codebase की Greppability बनाए रखने के लिए लागू किए जा सकने वाले कुछ नियम निकाले गए हैं

identifiers को split न करें

identifiers को split करना या dynamic तरीके से बनाना अच्छा विचार नहीं है
मान लें कि shipping_addresses और billing_addresses नाम की दो database tables हैं; order type के आधार पर table name को dynamic तरीके से बनाना अच्छा लग सकता है

const getTableName = (addressType: 'shipping' | 'billing') => {  
    return `${addressType}_addresses`  
}

यह DRY लग सकता है, लेकिन maintenance के लिए अच्छा नहीं है। कोई व्यक्ति codebase में shipping_addresses table name search करते समय इस हिस्से को चूक सकता है
identifiers को hardcode करना बेहतर तरीका है
searchability के लिए refactor किया गया code:

const getTableName = (addressType: 'shipping' | 'billing') => {  
    if (addressType === 'shipping') {  
        return 'shipping_addresses'  
    }  
    if (addressType === 'billing') {  
        return 'billing_addresses'  
    }  
    throw new TypeError('addressType must be billing or shipping')  
}

यही बात column names, object fields, और method/function names पर भी लागू होती है (JavaScript में method names को dynamic तरीके से बनाना आसान है)

पूरे stack में एक ही नाम इस्तेमाल करें

naming convention से मेल कराने के लिए application boundaries पर field names न बदलें
एक आम उदाहरण है PostgreSQL style के snake_case identifiers को JavaScript में लाकर camelCase में बदल देना, जो अच्छा नहीं है
इससे search मुश्किल हो जाती है। सब कुछ ढूँढ़ने के लिए एक की जगह दो strings search करनी पड़ती हैं

const getAddress = async (id: string) => {  
    const address = await getAddressById(id)  
    return {  
        streetName: address.street_name,  
        zipCode: address.zip_code,  
    }  
}

इसके बजाय object को सीधे return करना बेहतर है

const getAddress = async (id: string) => {  
    return await getAddressById(id)  
}

nested से flat बेहतर है

Python के Zen से प्रेरित होकर, namespaces को संभालते समय folder/object structure को nested करने के बजाय flat रखना ज़्यादातर मामलों में बेहतर है
अगर translation file config के लिए दो विकल्प हों:

{  
    "auth": {  
        "login": {  
            "title": "Login",  
            "emailLabel": "Email",  
            "passwordLabel": "Password",  
        },  
        "register": {  
            "title": "Register",  
            "emailLabel": "Email",  
            "passwordLabel": "Password",  
        }  
    }  
}

{  
    "auth.login.title": "Login",  
    "auth.login.emailLabel": "Email",   
    "auth.login.passwordLabel": "Password",  
    "auth.register.title": "Login",  
    "auth.register.emailLabel": "Email",  
    "auth.register.passwordLabel": "Password",  
}

दूसरा विकल्प चुनना बेहतर है। keys आसानी से मिल जाती हैं, और t('auth.login.title') की तरह refer किया जा सकता है
React component structure को देखें:

./components/AttributeFilterCombobox.tsx  
./components/AttributeFilterDialog.tsx  
./components/AttributeFilterRating.tsx  
./components/AttributeFilterSelect.tsx

यह नीचे जैसी structure से बेहतर मानी जाती है

./components/attribute/filter/Combobox.tsx  
./components/attribute/filter/Dialog.tsx  
./components/attribute/filter/Rating.tsx  
./components/attribute/filter/Select.tsx

search के नज़रिए से, Dialog जैसे सामान्य नाम की बजाय AttributeFilterCombobox जैसे namespace वाले पूरे component को search किया जा सकता है

GN⁺ की राय

यह blog post codebase maintain करते समय identifiers search करने के महत्व को अच्छी तरह समझाती है
identifiers को dynamic तरीके से बनाना या application boundaries पर names बदलना code maintenance को कठिन बना देता है। identifiers एकसमान और स्पष्ट होने चाहिए
इसके बजाय identifiers को hardcode करना और namespaces को flat रखना search के नज़रिए से बेहतर है
code readability और maintainability बढ़ाने के लिए इन सिद्धांतों को project में लागू करना अच्छा रहेगा
लेखक के सुझाए नियमों के अलावा Self-Documenting Code लिखना, अर्थपूर्ण comments का उपयोग करना आदि भी code quality बढ़ाने के अच्छे तरीके हैं

5 टिप्पणियां

nowpark 2024-09-06

इसे json के full path में बदल दीजिए—मैं एक ऐसा टूल भी छोड़ रहा हूँ जो इसे greppable बनाता है!

https://hi.news.hada.io/topic?id=3159

botplaysdice 2024-09-05

अच्छा है... greppability...

ahwjdekf 2024-09-04

उपयोगी जानकारी को जहाँ तक संभव हो, एक ही लाइन में लिखना भी उपयोगी लगता है।

roxie 2024-09-09

अच्छा है

GN⁺ 2024-09-04

Hacker News की राय

फ़ंक्शन नाम और क्लास नाम जैसे symbols को खोजकर ढूंढना, कोड का syntax समझने वाले टूल्स इस्तेमाल करने की तुलना में कमज़ोर तरीका है
- सिर्फ "Go to Definition" और "Find Usages" फीचर से भी text search की ज़रूरत काफ़ी कम हो सकती है
- पिछले 10 सालों में ज़्यादातर सिर्फ यूज़र को दिखने वाले strings ही खोजे हैं
- ऐसे पोस्ट का मतलब है कि लेखक को अपनी भाषा के लिए बेहतर tools सीखने में समय लगाना चाहिए
- सिर्फ एक अच्छा IDE भी बहुत समय बचा सकता है
अगर grep टूल में "super case-insensitive" mode हो तो वह उपयोगी होगा
- उदाहरण के लिए, "FooBar|first_name" खोजते समय उसे expand करके हर case को match करने देना
- यह default न होना चाहिए, ऐसी स्थिति की कल्पना करना मुश्किल है
greppability के समर्थन में
- Swedish में "grep-bar" या "grep-barhet" जैसे शब्द वास्तव में मौजूद हैं
- "greppbar" का मतलब "समझ में आने वाला" है, और "greppbarhet" का मतलब "समझे जा सकने की संभावना" है
Hamilton को डिज़ाइन करते समय लक्ष्य यह था कि function definitions और उनके downstream उपयोगों को आसानी से grep किया जा सके
- Python data transformation की दुनिया में ऐसा codebase बनाना आसान है जहाँ grep ज़्यादा मददगार नहीं होता
'greppable' अपने आप में आम तौर पर इस्तेमाल होने वाला शब्द/कॉन्सेप्ट नहीं है
- मैं इसे लंबे समय से एक organizing principle की तरह इस्तेमाल करता आया हूँ
- यह code को structure करने के सबसे अच्छे तरीकों में से एक है
conditional string interpolation का इस्तेमाल करने वाला एक जटिल उदाहरण देखा है
- जब मैं पहली बार project में शामिल हुआ, तब UI में दिखे तीन शब्दों को ढूंढने में बहुत ज़्यादा समय लग गया
- बाद में मैंने इस code को बदलकर ऐसे strings कर दिए जिन्हें आसानी से grep किया जा सके
कई coding styles और tools, line length चाहे जो भी हो, string constants को एक ही line में रखते हैं
- ताकि program output में string देखकर code में वही string खोजी जा सके
Rust, Javascript, Lisp में function definition से पहले keyword होते हैं, जिससे search आसान हो जाती है
- C में ऐसे keywords नहीं होते, इसलिए सिर्फ function name ही खोजा जा सकता है
- कुछ C coding rules, definitions को दो lines में बाँटते हैं ताकि search आसान हो सके
greppability से सहमत हूँ, लेकिन boundaries के पार नाम एक जैसे रखने से असहमत हूँ
- एक symbol का सिर्फ एक domain में मौजूद होना cognitive load कम करता है
code searchability अच्छी बात है, लेकिन उदाहरण जानबूझकर error की संभावना बढ़ाते हैं
- string condition जोड़ने से input और output के बीच mismatch की संभावना पैदा होती है
- dictionary को flatten करने से typo होने की संभावना बढ़ जाती है
- typos आम हैं, और जब वे कई codebases में copy हो जाते हैं तो उन्हें ठीक करना मुश्किल हो जाता है