Somo Hili Linahusu Nini Hasa

Si sintaksia tu

Si “msimbo safi” tu

Si taratibu za GitHub tu

Somo hili linahusu nidhamu ya uhandisi

Ukweli Mgumu

Mradi mara chache hushindwa kwa sababu watu hawawezi kuandika msimbo wowote.

Mradi mara nyingi hushindwa kwa sababu msimbo unakuwa:

Usioeleweka

Usiojaribiwa

Usiokaguliwa

Mgumu kubadilisha

Mtazamo Mbaya wa Mwanafunzi

Mtazamo Sahihi wa Uhandisi

Mhandisi mtaalamu anauliza:

Je, mtu mwingine anaweza kuelewa hii haraka?

Je, hii inaweza kubadilishwa kwa usalama baadaye?

Je, hii inaweza kujaribiwa?

Je, hii inaweza kukaguliwa vizuri?

Je, hii itafanya timu iwe haraka au polepole zaidi?

Gharama ya Msimbo Mbaya

Msimbo mbaya husababisha:

Hitilafu zaidi

Ujumuishaji wa wanachama wapya polepole

Utatuzi wa matatizo wenye uchungu

Kazi iliyorudiwa

Vipengele vilivyovunjika baada ya mabadiliko

Hofu ya kugusa msimbo

Faida ya Msimbo Mzuri

Msimbo mzuri hutoa:

Uendelezaji wa haraka

Ushirikiano rahisi

Urekebishaji salama

Ukaguzi bora

Uaminifu zaidi

Bidhaa thabiti zaidi

Ujumbe Muhimu

Hati Inaweza Kufanya Kazi. Mfumo Lazima Udumu.

Msimbo Husomwa Zaidi Kuliko Unavyoandikwa

Ukweli:

Unaandika kazi mara moja

Wenzako wa timu wanaisoma mara nyingi

Wewe wa baadaye unaisoma miezi baadaye bila kumbukumbu

Kwa hivyo:

Usomaji si hiari

Usomaji ni sehemu ya usahihi

Mfano Mbaya: “Inafanya Kazi” Haitoshi

def f(x, y, z):
    if x:
        if y > 0:
            return z * 0.2
    return 0

Matatizo:

f ni nini? Inahesabu nini?

x, y, z ni nini?

0.2 inawakilisha nini?

Hakuna mtu anayeweza kukagua, kujaribu, au kudumisha hii kwa uhakika

Mfano Bora: Maana Lazima Ionekane

def calculate_discount(price, has_membership, loyalty_points):
    if not has_membership:
        return 0
    if loyalty_points <= 0:
        return 0
    return price * 0.2

Kilichoboreshwa:

Jina la kazi linaeleza madhumuni

Vigezo vina maana

Mantiki inasomeka kama sentensi

Mkaguzi anaweza kuthibitisha usahihi mara moja

Kiwango cha Uhandisi

Usiulize tu: “Je, inafanya kazi?”

Uliza pia:

Je, inasomeka?

Je, inajaribiwa?

Je, ni salama kubadilisha?

Je, ningeidhinisha hii katika PR?

Mfano wa Utoaji Majina Mbaya

def calc(a, b):
    return a * b

Matatizo:

calc inahesabu nini?

a na b ni nini?

Inaweza kuwa eneo, bei, chochote - haiwezekani kujua

Mkaguzi hawezi kuthibitisha usahihi

Mfano Bora wa Utoaji Majina

def calculate_total_price(unit_price, quantity):
    return unit_price * quantity

Faida:

Madhumuni yako wazi mara moja

Vigezo vinajieleza vyenyewe

Mkaguzi anaweza kuthibitisha: “Ndiyo, bei jumla = bei ya kila kipande × wingi”

Waendelezaji wa baadaye hawatatumia vibaya kazi hii

Utoaji Majina Mazuri Unazuia Nini

Hupunguza mkanganyiko wakati wa kusoma msimbo usiojulikana

Huzuia dhana potofu kuhusu tabia ya kazi

Huzuia matumizi mabaya ya vigezo

Huzuia hitilafu za baadaye kutokana na kutoelewana

Mfano Mbaya: Majukumu Mengi Sana

def register_user(user):
    validate_user(user)
    save_user_to_database(user)
    send_welcome_email(user)
    log_activity(user)
    notify_admin(user)

Matatizo:

Majukumu matano katika kazi moja

Haiwezekani kujaribu usajili bila kutuma barua pepe

Barua pepe ikishindwa, mtumiaji bado anahifadhiwa?

Haiwezekani kutumia tena hatua yoyote peke yake

Mfano Bora: Tenganisha Majukumu

def register_user(user):
    validate_user(user)
    save_user_to_database(user)

def onboard_user(user):
    send_welcome_email(user)
    log_activity(user)

def handle_registration(user):
    register_user(user)
    onboard_user(user)
    notify_admin(user)

Faida:

Kila kazi ina madhumuni wazi, moja

Kila moja inaweza kujaribiwa kwa kujitegemea

Kushughulikia kushindwa kunakuwa rahisi

Mfano Mbaya: Mantiki Iliyorudiwa

# In checkout.py
final_price = price - price * 0.1

# In invoice.py
final_price = price - price * 0.1

# In report.py
final_price = price - price * 0.1

Mfano Bora: Weka Mantiki ya Pamoja Katikati

def apply_discount(price, discount_rate):
    return price * (1 - discount_rate)

# Kila mahali:
final_price = apply_discount(price, 0.1)

Faida:

Chanzo kimoja cha ukweli

Badilisha mara moja, sahihisha kila mahali

Rahisi kujaribu

Rahisi kupata na kukagua

Mfano wa Msimbo Mgumu Kujaribu

def process_order(order_id):
    order = db.get_order(order_id)         # database call
    user = db.get_user(order.user_id)      # database call
    send_email(user.email, order.summary)  # side effect
    db.mark_processed(order_id)            # database call

Matatizo:

Haiwezekani kujaribu bila hifadhidata halisi

Haiwezekani kujaribu bila kutuma barua pepe halisi

Athari zote za pembeni zimeunganishwa kwa nguvu

Muundo Unaojaribiwa Zaidi

def process_order(order, user, email_sender, db):
    email_sender.send(user.email, order.summary)
    db.mark_processed(order.id)

Faida:

Vitegemezi vinaingizwa - rahisi kuiga

Kila kitegemezi kinaweza kujaribiwa kwa kujitegemea

Mantiki imetenganishwa na miundombinu

Saini ya kazi inakuambia haswa kinachohitajika

Ushughulikiaji Mbaya wa Hitilafu

def get_user_age(user):
    if user is None:
        return None
    if user.birthday is None:
        return None
    return calculate_age(user.birthday)

Hatari:

Mwenye kuita anapata None na hajui kwa nini

Hitilafu imefichwa na inaenea kwa kimya

Kutatua matatizo kunakuwa mchezo wa kubahatisha

Ushughulikiaji Bora wa Hitilafu

def get_user_age(user):
    if user is None:
        raise ValueError("User must not be None")
    if user.birthday is None:
        raise ValueError("User birthday is missing")
    return calculate_age(user.birthday)

Faida:

Hitilafu inaonekana mara moja

Ujumbe unakuambia haswa kilicho kibaya

Hitilafu inashikwa mapema, si mbali zaidi

Mfano Mgumu

def get_price(user, product):
    if user.is_member:
        if product.on_sale:
            if user.loyalty_points > 100:
                return product.price * 0.7
            else:
                return product.price * 0.8
        else:
            return product.price * 0.9
    else:
        if product.on_sale:
            return product.price * 0.95
        else:
            return product.price

Umeingizwa ndani sana, mgumu kufuata, rahisi kuanzisha hitilafu

Mfano Rahisi

def get_discount_rate(user, product):
    if not user.is_member and not product.on_sale:
        return 0
    if not user.is_member and product.on_sale:
        return 0.05
    if user.is_member and not product.on_sale:
        return 0.1
    if user.loyalty_points > 100:
        return 0.3
    return 0.2

def get_price(user, product):
    return product.price * (1 - get_discount_rate(user, product))

Tambarare, inasomeka, kila kesi ni wazi na inajaribiwa

Kanuni ya 7: Mabadiliko Madogo Yanashinda Mabadiliko Makubwa Yenye Fujo

Kanuni ya Uhandisi

Pendelea:

Kazi ndogo

Commits ndogo

PRs ndogo

Vitengo vidogo vya ukaguzi

Mtiririko Sahihi wa Msingi

Usifanye Kazi Moja kwa Moja kwenye Main

Main inapaswa kuwa tayari kusambazwa kila wakati

Commits za moja kwa moja zinaruka ukaguzi

Migongano ya kuunganisha inakuwa ya uharibifu

Hakuna njia ya kurudisha nyuma kwa usafi

Timu inapoteza uaminifu katika msimbo

Tawi Linawakilisha Nini

Majina mabaya ya tawi:

fix
my-branch
test123
update

Majina bora ya tawi:

feature/user-registration
fix/login-redirect-bug
chore/update-dependencies
refactor/split-order-service

Jina la tawi linapaswa kueleza nia ya kazi

Commits Zinapaswa Kusimulia Hadithi

fix
update
wip
asdf
changed stuff

fix: redirect to login after session timeout
feat: add email validation to registration
refactor: extract discount logic into helper
test: add edge cases for price calculator
docs: update API authentication section

PR Nzuri Inakaguliwa

Ndogo na inalenga kitu kimoja

Ina kichwa na maelezo wazi

Inaeleza kwa nini mabadiliko yalifanywa

Inajumuisha majaribio ikihitajika

Haichanganyi mabadiliko yasiyo husiana

PR Mbaya dhidi ya PR Nzuri

Mfano wa Muundo wa Hazina

project/
├── src/
│   ├── models/
│   ├── services/
│   ├── routes/
│   └── utils/
├── tests/
│   ├── unit/
│   └── integration/
├── .github/
│   └── workflows/
│       └── ci.yml
├── .gitignore
├── README.md
├── requirements.txt
├── Makefile
└── .env.example

Kwa Nini README Ni Muhimu

README inapaswa kumwambia mwanachama mpya wa timu:

Mradi unafanya nini

Jinsi ya kuuweka

Jinsi ya kuuendesha

Jinsi ya kuendesha majaribio

Jinsi ya kuchangia

README Nzuri Inajumuisha

Jina la mradi na maelezo ya mstari mmoja

Mahitaji ya awali (toleo la Python, vitegemezi)

Hatua za ufungaji

Jinsi ya kuendesha ndani ya nchi

Jinsi ya kuendesha majaribio

Vibadilishaji vya mazingira vinavyohitajika

Muhtasari wa muundo wa mradi

Miongozo ya kuchangia

Hazina Yako Ikiwa na Mkanganyiko, Timu Yako Inapungua Kasi

Majaribio Yanakupa Nini Kweli

Uhakika wa kubadilisha msimbo

Utatuzi wa matatizo haraka - majaribio yanaonyesha wapi mambo yalivunjika

Nyaraka za tabia inayotarajiwa

Mtandao wa usalama kwa urekebishaji

Uthibitisho kwamba msimbo wako unafanya kazi

Mfano Rahisi Sana

def add(a, b):
    return a + b

Kazi rahisi. Tunajuaje inafanya kazi kwa usahihi?

Tunaandika jaribio.

Mfano wa Msingi wa Pytest

def test_add_returns_sum():
    assert add(2, 3) == 5

Wazi, inasomeka, haraka kuendesha

Ikiwa add itavunjika, jaribio hili linashika mara moja

Mtu yeyote anaweza kuelewa jaribio hili linakagua nini

Majaribio Mazuri Yanakagua Zaidi ya Njia ya Furaha

Nini kingine tunapaswa kujaribu?

Nambari hasi

Thamani za sifuri

Nambari kubwa sana

Kutolingana kwa aina (ikihitajika)

Masharti ya mpaka

Kesi za hitilafu

Mfano: Majaribio Yenye Manufaa Zaidi

def test_add_positive_numbers():
    assert add(2, 3) == 5

def test_add_negative_numbers():
    assert add(-1, -2) == -3

def test_add_with_zero():
    assert add(0, 5) == 5
    assert add(5, 0) == 5

def test_add_mixed_signs():
    assert add(-3, 5) == 2

Kila jaribio lina jina wazi linaloeleza linakagua nini

Kinachotokea Bila Majaribio

Hitilafu zinafika uzalishaji

Urekebishaji unakuwa wa kutisha

Hakuna anayejua kama mabadiliko yalivunja kitu

Majaribio ya mikono ni polepole na hayategemewi

Kurudi nyuma kunaendelea kurudi

Timu inapoteza uaminifu katika msimbo

Kinachotokea na Majaribio

Hitilafu zinashikwa kabla ya kuunganisha

Urekebishaji ni salama na wa haraka

CI inashika kurudi nyuma kiotomatiki

Wanachama wapya wa timu wanaelewa tabia inayotarajiwa

Usambazaji unafanywa kwa uhakika

Kasi ya timu inaongezeka kwa muda

Kwa Nini CI Ni Muhimu

Ukaguzi wa Kawaida wa CI

Endesha majaribio yote (ya kitengo + ya ushirikiano)

Kagua uumbizo wa msimbo (black, prettier, n.k.)

Endesha linter (pylint, eslint, flake8)

Kagua maandishi ya aina (mypy)

Pima chanjo ya majaribio

Ukaguzi wa usalama

Ukaguzi wa ujenzi (je, mradi unakusanya/kujenga?)

Mfano wa GitHub Actions

name: Python Checks
on:
  pull_request:
  push:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: pytest

Hii Inafanikisha Nini

Kila PR inaendesha majaribio kiotomatiki

PRs zilizovunjika haziwezi kuunganishwa (na ulinzi wa tawi)

Timu haihitaji kukumbuka kuendesha majaribio

Maoni ni ya haraka na thabiti

Ukaguzi wa Chanjo

Chanjo ya majaribio inapima ni kiasi gani cha msimbo wako kinafanyiwa mazoezi na majaribio.

Chanjo ya juu haimaanishi hakuna hitilafu

Chanjo ya chini inamaanisha maeneo makubwa hayajajaribiwa

Chanjo ni mwongozo, si dhamana

Kanuni ya Vitendo ya Ubora

Malengo mazuri kwa miradi mingi:

70-85% chanjo ya majaribio kama kiwango cha msingi

Mantiki yote muhimu ya biashara imejaribiwa

Kesi zote za ukingo za kazi kuu zimejaribiwa

CI lazima ipite kabla ya kuunganisha (bila ubaguzi)

Ukaguzi wa linter na muumbizaji katika kila PR

Kwa Nini Timu Zinakagua Msimbo

Kushika hitilafu kabla hazijafika uzalishaji

Kushiriki maarifa ndani ya timu

Kudumisha ubora thabiti wa msimbo

Kusambaza umiliki wa msimbo

Kufundisha na kujifunza kutoka kwa kila mmoja

Kujenga uaminifu wa timu

Ukaguzi Dhaifu dhidi ya Ukaguzi Madhubuti

Jinsi ya Kutoa Ukaguzi Madhubuti wa Msimbo

Kagua:

Usahihi - je, mantiki inafanya inachopaswa?

Usomaji - je, unaweza kuelewa bila kuuliza?

Utoaji majina - je, majina ni wazi na sahihi?

Kurudia - je, kuna kitu kinachorudiwa bila sababu?

Ushughulikiaji wa hitilafu - je, kesi za ukingo zimeshughulikiwa?

Majaribio - je, kuna majaribio kwa mantiki mpya?

Upeo - je, PR inabaki kwenye lengo?

Mtazamo wa Mkaguzi

Wakati wa ukaguzi, jibu maswali haya:

Je, ninaelewa msimbo huu unafanya nini?

Je, ningejisikia vizuri kudumisha hii?

Je, kuna kitu ambacho kinaweza kuvunjika kwa kimya?

Je, kuna majaribio yanayokosekana?

Je, maelezo ya PR ni sahihi?

Je, mwanachama mpya wa timu angeelewa hii?

Maoni Mabaya ya Ukaguzi

Kwa nini ni dhaifu:

Haielezi nini kiko vibaya

Haielezi kwa nini kiko vibaya

Haipendekezi uboreshaji

Inaonekana kama shambulio, si maoni

Inapoteza muda wa mwandishi

Maoni Bora ya Ukaguzi

Kwa nini inafanya kazi:

Inaeleza tatizo

Inaonyesha athari

Inapendekeza marekebisho mahususi

Inamtendea mwandishi kama mshirikiano

Tumia Maswali Kupunguza Msuguano

Badala ya amri, tumia maswali ya udadisi:

“Nini kinatokea ikiwa ingizo hili ni hasi?”

“Je, tunaweza kurahisisha hii na kurudi mapema?”

“Je, kuna sababu hatutumii msaidizi uliopo kwa hii?”

“Je, ingekuwa wazi zaidi kutoa hii katika kazi tofauti?”

Mifano ya Lengo Madhubuti la Ukaguzi

Mkaguzi madhubuti anaona:

Nambari za kichawi bila maelezo

Ushughulikiaji wa hitilafu unaokosekana kwa kesi za ukingo

Mantiki iliyorudiwa ambayo inapaswa kutolewa

Kazi zinazofanya zaidi ya kitu kimoja

Kanuni za utoaji majina zisizo na msimamo

Majaribio yanayokosekana au yasiyotosha

Wasiwasi wa usalama (siri zilizowekwa kwa nguvu, SQL injection, n.k.)

Soma Msimbo Huu Kama Mkaguzi

def calc(items):
    t = 0
    for i in items:
        if i["type"] == "book":
            t += i["price"] * 0.9
        else:
            t += i["price"]
    return t

Kama mkaguzi, uliza:

calc inahesabu nini?

0.9 inamaanisha nini? Kwa nini vitabu haswa?

Nini kinatokea ikiwa kipengee hakina ufunguo wa “type” au “price”?

Majaribio yako wapi?

Toleo Bora Zaidi Linalokaguliwa

BOOK_DISCOUNT_RATE = 0.1

def get_item_price(item):
    price = item["price"]
    if item["type"] == "book":
        return price * (1 - BOOK_DISCOUNT_RATE)
    return price

def calculate_cart_total(items):
    return sum(get_item_price(item) for item in items)

Maboresho:

Nambari ya kichawi imebadilishwa na thamani thabiti yenye jina

Mantiki ya bei imetolewa katika kazi yake

Kila kazi inajaribiwa kwa kujitegemea

Wakaguzi Wasipaswi Kufanya Nini

Kushughulika na mtindo wakati kuna linter kwa hilo

Kuandika upya msimbo wa mwandishi kwa mtindo wao

Kuidhinisha bila kusoma

Kuzuia PR kwa upendeleo wa kibinafsi (si usahihi)

Kuwa wa kiburi au wa dharau

Kuchelewa ukaguzi kwa siku bila mawasiliano

Usipoelewa Msimbo, Usiidhinishe

Jinsi ya Kupokea Ukaguzi Kitaalamu

Jibu Baya la Ukaguzi

Majibu haya yanafunga ushirikiano na kuondoa uaminifu

Jibu Zuri la Ukaguzi

Majibu haya yanajenga uaminifu na kuimarisha timu

Ukaguzi Si Kuhusu Kushinda

Matumizi Mazuri ya GenAI

Tengeneza msimbo wa boilerplate kuokoa muda

Andaa kesi za majaribio kwa kazi zilizopo

Eleza msimbo au maktaba zisizojulikana

Pendekeza mbinu mbadala

Saidia kuandika nyaraka

Saidia katika utatuzi wa matatizo kwa kuchambua ujumbe wa hitilafu

Kagua msimbo kabla ya kuwasilisha PR

Matumizi Dhaifu ya GenAI

Kutumia AI bila kuelewa:

Usipoweza kueleza msimbo, si wako

Msimbo uliotengenezwa na AI wenye hitilafu usizozielewa ni mbaya zaidi kuliko kutokuwa na msimbo

Matumizi Madhubuti ya GenAI

Maombi bora, matokeo bora:

Maombi mahususi na yenye lengo hutoa matokeo yenye manufaa na yanayokaguliwa

Mfano Mzuri wa Ombi la Kutengeneza Majaribio

# Prompt to AI:
"Write pytest tests for this function.
Include: happy path, negative input, zero, empty list, and type error.
Use descriptive test names."

# Function:
def calculate_average(numbers):
    if not numbers:
        raise ValueError("Cannot average empty list")
    return sum(numbers) / len(numbers)

Ombi ni mahususi kuhusu nini cha kujaribu na jinsi ya kutaja majaribio

Bado unakagua na kurekebisha majaribio yaliyotengenezwa

Mfano Mzuri wa Ombi la Ukaguzi wa Msimbo

# Prompt to AI:
"Review this function as a senior engineer.
Check for:
- edge cases
- naming clarity
- error handling
- testability
- any potential bugs

Be specific and suggest improvements."

Tumia AI kama “mkaguzi wa kwanza” kabla mwenzako wa timu hakagui

Hii inashika matatizo dhahiri na kuokoa muda wa mkaguzi

Muunganisho na VS Code na Wahariri

Zana za AI zenye manufaa kwa uendelezaji:

GitHub Copilot - mapendekezo ya msimbo ndani ya mstari

Claude Code (CLI) - msaidizi wa AI kwenye terminal

Cursor - kihariri cha msimbo chenye AI asili

Codeium - ukamilishaji otomatiki wa bure wa AI

Matumizi mazuri:

Kukamilisha otomatiki mifumo inayorudiwa

Kutengeneza docstrings

Kueleza sehemu ngumu za msimbo

Kupendekeza muundo wa majaribio

Kanuni ya Msimbo Uliotengenezwa na AI

Kabla ya kuunganisha msimbo wowote uliotengenezwa na AI, lazima:

Uelewe - soma kila mstari

Ueleze - uweze kueleza unafanya nini na kwa nini

Ujaribu - uthibitishe na majaribio yako mwenyewe

Uidhinishe - uitendee kama vile umeandika wewe mwenyewe katika PR yako

Lengo la Onyesho la Moja kwa Moja

Baada ya onyesho hili, unapaswa kuweza:

Kusoma tofauti ya PR kwa makini

Kutambua angalau aina 5 za matatizo

Kuandika maoni ya ukaguzi yenye kujenga

Kupendekeza maboresho mahususi

Kutofautisha kati ya matatizo yanayozuia na mapendekezo

Kazi ya Nyumbani: Kagua Pull Request Kama Mhandisi

Kazi:

Pata PR ya chanzo huria kwenye GitHub (au tumia moja iliyotolewa na mwalimu)

Andika ukaguzi wenye angalau maoni 5 yenye maudhui

Kila maoni lazima itambue tatizo mahususi na ipendekeze uboreshaji

Mahitaji ya kuwasilisha:

Kiungo cha PR uliyoikagua

Maoni yako ya ukaguzi (picha ya skrini au markdown)

Tafakuri fupi: ulijifunza nini kutoka kwenye kukagua msimbo wa mtu mwingine?

Ujumbe wa Mwisho