Coffee break #103. Sa pagtatanggol sa "Clean Code": 100 walang hanggang mga tip

Pinagmulan: Hackernoon "Clean Code" ni Robert C. Martin ay ang pinaka inirerekomendang programming book sa lahat ng oras. Maghanap ng mga aklat gamit ang query na "pinakamahusay na aklat para sa mga developer ng software" at halos garantisadong mahanap mo ang aklat na ito sa mga resulta ng paghahanap. At habang ang ilang mga tao ay nararamdaman na ang Malinis na Kodigo ay hindi nararapat na bigyang pansin, ako ay mangangatuwiran na ang gayong mga damdamin ay lubos na nagkakamali. Oo, ang ilan sa mga payo sa aklat ay kaduda-dudang. Oo, ang ilan sa mga nilalaman ay tila luma na. Oo, nakakalito ang ilang halimbawa. Totoo ang lahat. Ngunit huwag tayong magmadaling magdiskwento sa maraming kapaki-pakinabang na tip na inaalok ng aklat na ito! Ang ganap na pagwawalang-bahala sa Clean Code dahil lamang sa ilang masamang ideya ay hindi ang pinakamahusay na solusyon. Kaya, nang walang karagdagang ado, tingnan natin ang pinakamahusay na mga tip na inaalok ng Clean Code! Susuriin natin ang bawat kabanata, na ibubuod ang mga ideyang iniaalok ni Uncle Bob at ng kanyang mga kasamang may-akda.

Kabanata 1: Malinis na Code

1. Ang kabuuang dami ng kalat ay tumataas sa paglipas ng panahon.

2. Ang pagpapanumbalik ng hindi napapanahong sistema mula sa simula ay napakahirap. Ang refactoring at incremental na mga pagpapabuti ay ang pinakamahusay na opsyon para dito.

3. Sa isang magulo na codebase, ang mga gawain na dapat tumagal lamang ng ilang oras ay maaaring tumagal ng mga araw o linggo upang makumpleto.

4. Maglaan ng oras upang kumilos nang mabilis.

5. Ang malinis na code ay gumagawa ng isang bagay nang maayos. Masyadong marami ang sinusubukang gawin ng masamang code.

6. Ang malinis na code ay mahusay na nasubok.

7. Kapag nagbabasa ng mahusay na pagkakasulat na code, ginagawa ng bawat function ang halos kung ano ang iyong inaasahan.

8. Kung hindi ka sumasang-ayon sa isang alituntuning itinuro ng isang taong may maraming taon ng karanasan, dapat mong isaalang-alang ang kanilang pananaw bago ito balewalain.

9. Ang code ay binabasa nang mas madalas kaysa sa nakasulat.

10. Ang code na mas madaling basahin ay mas madaling baguhin.

11. Iwanan ang codebase nang mas mahusay kaysa noong nakita mo ito (Boy Scout Rule).

Kabanata 2: Ang Kahulugan ng mga Pangalan

1. Maingat na piliin ang iyong mga variable na pangalan.

2. Ang pagpili ng magagandang pangalan ay mahirap.

3. Ang pangalan ng isang variable o function ay dapat magpahiwatig kung ano ito at kung paano ito ginagamit.

4. Iwasang gumamit ng mga single-character na pangalan ng variable, maliban sa mga karaniwang ginagamit na pangalan, gaya ng i para sa isang counter variable sa isang loop.

5. Iwasang gumamit ng mga abbreviation sa mga variable na pangalan.

6. Ang mga variable na pangalan ay dapat na binibigkas upang maaari mong pag-usapan ang mga ito at sabihin ang mga ito nang malakas.

7. Gumamit ng mga variable na pangalan na madaling mahanap.

8. Ang mga klase at bagay ay dapat may mga pangalan sa anyo ng mga pangngalan.

9. Ang mga pangalan ng pamamaraan at function ay dapat na mga pandiwa o pares ng pandiwa-pangngalan.

Kabanata 3: Mga Pag-andar

1. Dapat maliit ang mga function.

2. Ang function ay dapat magsagawa ng isang aksyon.

3. Ang mga function ay dapat na may mga mapaglarawang pangalan.

4. I-extract ang code sa if/else body o ilipat ang mga statement sa malinaw na pinangalanang function.

5. Limitahan ang bilang ng mga argumento na kinukuha ng isang function.

6. Kung ang isang function ay nangangailangan ng maraming argumento sa pagsasaayos, isaalang-alang ang pagsasama-sama ng mga ito sa iisang variable ng mga parameter ng pagsasaayos.

7. Ang mga function ay dapat na dalisay, na nangangahulugang wala silang mga side effect at hindi binabago ang kanilang mga input argument.

8. Ang function ay dapat na isang command o isang query, ngunit hindi pareho nang sabay-sabay (Command Query Separation).

9. Mas mainam na alisin ang mga error at exception sa code kaysa mag-iwan ng mga error sa code.

10. I-extract ang duplicate na code sa mga function na malinaw na pinangalanan (Huwag Ulitin ang Iyong Sarili).

11. Pinapadali ng mga unit test ang refactoring.

Kabanata 4: Mga Komento

1. Maaaring mali ang mga komento. Maaaring mali ang mga ito sa simula, o maaaring tumpak ang mga ito sa simula at pagkatapos ay luma na sa paglipas ng panahon habang nagbabago ang code.

2. Gumamit ng mga komento upang ilarawan kung bakit ito nakasulat sa paraang ito, sa halip na ipaliwanag kung ano ang nangyayari.

3. Madalas na maiiwasan ang mga komento sa pamamagitan ng paggamit ng malinaw na pinangalanang mga variable at pagkuha ng mga seksyon ng code sa malinaw na pinangalanang mga function.

4. I-prefix ang TODO na mga komento na may pare-parehong prefix para mas madaling mahanap ang mga ito. Suriin at linisin ang iyong mga komento sa TODO sa pana-panahon.

5. Huwag gumamit ng Javadocs para lamang sa paggamit ng mga ito. Ang mga komentong naglalarawan kung ano ang ginagawa ng isang pamamaraan, kung anong mga argumento ang kinakailangan, at kung ano ang ibinabalik nito ay kalabisan sa pinakamainam at nakakapanlinlang sa pinakamasama.

6. Dapat isama sa mga komento ang lahat ng nauugnay na impormasyon at konteksto na kakailanganin ng mambabasa. Huwag maging tamad sa pagsulat ng komento.

7. Ang mga komento sa log at mga komento ng may-akda ng file ay hindi kailangan dahil sa kontrol ng bersyon at git blame.

8. Huwag magkomento ng dead code. Tanggalin mo na lang. Kung sa tingin mo ay kakailanganin mo ang code sa hinaharap, para iyan ang version control.

Kabanata 5: Pag-format

1. Bilang isang team, pumili ng isang hanay ng mga panuntunan para sa pag-format ng iyong code, at pagkatapos ay patuloy na ilapat ang mga panuntunang iyon. Anuman ang mga patakaran na sinasang-ayunan mo, kailangan mong magkaroon ng isang kasunduan.

2. Gumamit ng awtomatikong pag-format ng code at isang code analyzer. Huwag umasa sa mga tao na manual na mahanap at ayusin ang bawat error sa pag-format. Ito ay hindi mabisa, hindi produktibo at isang pag-aaksaya ng oras kapag sinusuri ang code.

3. Magdagdag ng mga patayong puwang sa pagitan ng mga linya ng code upang biswal na paghiwalayin ang mga kaugnay na bloke ng code. Ang kailangan mo lang ay gumawa ng isang bagong linya sa pagitan ng mga grupo.

4. Ang mga maliliit na file ay mas madaling basahin, maunawaan, at ilipat kaysa sa malalaking file.

5. Dapat ideklara ang mga variable malapit sa kung saan ginagamit ang mga ito. Para sa maliliit na function ito ay karaniwang nasa tuktok ng function.

6. Kahit na para sa mga maikling function o kung mga pahayag, i-format pa rin ang mga ito nang tama sa halip na isulat ang mga ito sa isang linya.

Kabanata 6: Mga Bagay at Istruktura ng Data

1. Ang mga detalye ng pagpapatupad sa isang bagay ay dapat nakatago sa likod ng interface ng object. Sa pamamagitan ng pagbibigay ng interface para sa paggamit ng mga mamimili ng isang bagay, ginagawa mong mas madali ang mga detalye ng pagpapatupad ng refactor sa ibang pagkakataon nang hindi nagdudulot ng mga paglabag sa pagbabago. Pinapadali ng mga abstraction ang refactoring.

2. Anumang ibinigay na piraso ng code ay dapat na walang kaalaman sa mga panloob ng bagay na pinapatakbo nito.

3. Kapag nagtatrabaho sa isang bagay, dapat mong hilingin dito na magsagawa ng isang utos o query, sa halip na tanungin ito tungkol sa mga panloob nito.

Kabanata 7: Pagwawasto ng mga Mali

1. Ang paghawak ng error ay hindi dapat makagambala sa natitirang code sa module.

2. Mas mainam na alisin ang mga error at exception sa code kaysa mag-iwan ng mga error sa code.

3. Sumulat ng mga pagsubok na may mga error upang matiyak na ang iyong code ay kinikilala ang mga ito at hindi ito makaligtaan.

4. Ang mga mensahe ng error ay dapat na nagbibigay-kaalaman, kasama ang lahat ng kinakailangang konteksto na maaaring kailanganin ng isang tao na i-troubleshoot nang epektibo.

5. Ang pagbabalot ng mga third-party na API sa isang manipis na layer ng abstraction ay nagpapadali sa pagpapalit ng isang library ng isa pa sa hinaharap.

6. Ang pagbalot ng mga third-party na API sa isang manipis na layer ng abstraction ay ginagawang mas madali upang kutyain ang library sa panahon ng pagsubok.

7. Gamitin ang pattern ng Espesyal na Case o Null Object na pattern upang pangasiwaan ang pambihirang pag-uugali, tulad ng kapag walang partikular na data.

Kabanata 8: Mga Hangganan

1. Nakakatulong ang mga third-party na library na pabilisin ang paghahatid ng produkto sa pamamagitan ng pagpapahintulot sa iyo na mag-outsource ng iba't ibang gawain.

2. Sumulat ng mga pagsubok upang matiyak na ginagamit mo nang tama ang third party na library.

3. Gamitin ang pattern ng adaptor upang i-bridge ang agwat sa pagitan ng API ng isang third-party na library at ng API na gusto mong magkaroon.

4. Ang pagbabalot ng mga third-party na API sa isang manipis na layer ng abstraction ay nagpapadali sa pagpapalit ng isang library ng isa pa sa hinaharap. (Ulitin mula sa Kabanata 7)

5. Ang pagbalot ng mga third-party na API sa isang manipis na layer ng abstraction ay ginagawang mas madali upang kutyain ang library sa panahon ng pagsubok. (Ulitin mula sa Kabanata 7)

6. Subukang huwag sabihin sa iyong application ang masyadong maraming impormasyon tungkol sa mga detalye ng anumang third party na library.

7. Mas mabuting umasa sa kung ano ang kinokontrol mo kaysa sa hindi mo kontrolado.

Kabanata 9: Mga Pagsusulit sa Yunit

1. Ang test code ay dapat kasinglinis ng production code (na may ilang mga pagbubukod, kadalasang nauugnay sa memorya o kahusayan).

2. Habang nagbabago ang production code, nagbabago rin ang test code.

3. Nakakatulong ang mga pagsubok na panatilihing flexible at mapanatili ang iyong production code.

4. Nagbibigay-daan sa iyo ang mga pagsubok na gumawa ng mga pagbabago, na nagbibigay-daan sa iyong kumpiyansa na mag-refactor nang walang takot na hindi ito mapansin mismo.

5. Buuin ang iyong mga pagsubok gamit ang Arrange-Act-Assert (kilala rin bilang Build-Operate-Check, Setup-Exercise-Verify, o Given-When-Then) pattern.

6. Gumamit ng mga function na partikular sa domain upang gawing mas madaling isulat at basahin ang mga pagsubok.

7. Puntos ng isang konsepto sa bawat pagsubok.

8. Dapat mabilis ang mga pagsusulit.

9. Ang mga pagsusulit ay dapat na independyente.

10. Ang mga pagsusulit ay dapat na paulit-ulit.

11. Ang mga pagsusulit ay hindi dapat mangailangan ng kumpirmasyon.

12. Ang mga pagsusulit ay dapat na nakasulat sa isang napapanahong paraan, ilang sandali bago o pagkatapos isulat ang code ng produksyon, hindi pagkalipas ng ilang buwan.

13. Kung masama ang iyong mga pagsubok, asahan na may mga bug sa iyong code.

Kabanata 10: Mga Klase

1. Dapat maliit ang mga klase.

2. Ang mga klase ay dapat lamang maging responsable para sa isang bagay at dapat magkaroon lamang ng isang dahilan para sa pagbabago (isang prinsipyo ng responsibilidad).

3. Kung hindi ka makabuo ng isang malinaw na pangalan para sa klase, malamang na ito ay masyadong malaki.

4. Ang iyong trabaho ay hindi nagtatapos kapag nakakuha ka ng isang piraso ng code upang gumana. Ang susunod na hakbang ay ang refactor at linisin ang code.

5. Ang paggamit ng maraming maliliit na klase sa halip na ilang malalaking klase sa iyong aplikasyon ay nakakabawas sa dami ng impormasyong dapat maunawaan ng isang developer kapag gumagawa sa anumang gawain.

6. Ang pagkakaroon ng magandang test suite ay nagbibigay-daan sa iyong mag-refactor nang may kumpiyansa kapag hinati mo ang malalaking klase sa mas maliliit na klase.

7. Ang mga klase ay dapat na bukas para sa extension, ngunit sarado para sa pagbabago (open-closed na prinsipyo).

8. Ang mga interface at abstract na klase ay gumagawa ng mga tahi na nagpapadali sa pagsubok.

Kabanata 11: Sistema

1. Gumamit ng dependency injection upang bigyan ang mga developer ng flexibility na ipasa ang anumang bagay na may naaangkop na interface sa ibang klase.

2. Gumamit ng dependency injection upang lumikha ng mga interface sa pagitan ng mga bagay sa iyong application upang gawing mas madali ang pagsubok.

3. Ang mga sistema ng software ay hindi tulad ng isang gusali na kailangang idisenyo nang maaga. Mas katulad sila ng mga lungsod na lumalago at lumalawak sa paglipas ng panahon, umaangkop sa mga kasalukuyang pangangailangan.

4. Ipagpaliban ang paggawa ng desisyon hanggang sa huling kritikal na sandali.

5. Gumamit ng wikang tukoy sa domain upang ang mga eksperto at developer ng domain ay gumamit ng parehong terminolohiya.

6. Huwag gawing kumplikado ang iyong sistema. Gamitin ang pinakasimpleng bagay na gumagana.

Kabanata 12: Deployment

1. Hindi mabe-verify ang mga system na hindi masusuri, at hindi kailanman dapat i-deploy ang mga system na hindi ma-verify.

2. Ang mga pagsusulit sa pagsulat ay humahantong sa mas mahusay na disenyo dahil ang code na madaling subukan ay kadalasang gumagamit ng dependency injection, mga interface, at abstraction.

3. Ang isang mahusay na hanay ng mga pagsubok ay mag-aalis ng takot na masira ang iyong aplikasyon habang nagre-refactor.

4. Ang pagdoble ng code ay lumilikha ng mas maraming panganib dahil mas maraming lugar sa code na maaaring baguhin at mas maraming lugar kung saan maaaring itago ang mga error.

5. Ang code na isinulat mo ngayon ay mas madaling maunawaan dahil ikaw ay malalim na kasangkot sa pag-unawa dito. Hindi madali para sa iba na mabilis na maabot ang parehong antas ng pang-unawa.

6. Karamihan sa gastos ng isang software project ay nauugnay sa pangmatagalang pagpapanatili.

7. Ang mga pagsusulit ay nagsisilbing buhay na dokumentasyon kung paano dapat (at ginagawa) ang iyong aplikasyon.

8. Huwag nang gumalaw pa sa sandaling gumana ang iyong code. Maglaan ng oras upang gawin itong mas malinaw at mas maintindihan.

9. Ang susunod na taong magbabasa ng iyong code sa malapit na hinaharap ay malamang na ikaw. Maging mabait sa iyong sarili sa hinaharap sa pamamagitan ng pagsulat ng code na madaling maunawaan.

10. Labanan ang dogma. Yakapin ang pragmatismo.

11. Ito ay tumatagal ng mga dekada upang maging isang mahusay na software engineer. Mapapabilis mo ang iyong curve sa pagkatuto sa pamamagitan ng pag-aaral mula sa mga eksperto sa paligid mo at pag-aaral ng mga karaniwang ginagamit na pattern ng disenyo.

Kabanata 13: Paralelismo

1. Mahirap ang pagsulat ng parallel code.

2. Ang mga paminsan-minsang bug at mga problema na mahirap kopyahin ay kadalasang mga problema sa pagkakatugma.

3. Hindi ginagarantiya ng pagsubok na magiging walang bug ang iyong application, ngunit mababawasan nito ang panganib.

4. Alamin ang tungkol sa mga karaniwang problema sa concurrency at ang kanilang mga posibleng solusyon.

Kabanata 14: Sequential Refinement

1. Ang malinis na code ay hindi karaniwang nagsisimula sa isang blangkong slate. Sumulat ka muna ng magaspang na solusyon at pagkatapos ay i-refactor ito upang maging mas malinis.

2. Isang pagkakamali na huminto sa paggawa sa code kapag nagsimula na itong gumana. Maglaan ng oras upang pagandahin pa ito pagkatapos na gumana na ito.

3. Unti-unting lumalago ang kaguluhan.

4. Kung nakita mo ang iyong sarili sa isang bind kung saan ang pagdaragdag ng mga tampok ay masyadong mahirap o masyadong tumatagal, ihinto ang pagsusulat ng mga tampok at simulan ang refactoring.

5. Ang incremental na pagbabago ay kadalasang mas mahusay kaysa sa muling pagtatayo mula sa simula.

6. Gumamit ng Test-Driven Development (TDD) para gumawa ng malaking bilang ng napakaliit na pagbabago.

7. Ang magandang disenyo ng software ay kinabibilangan ng paghihiwalay ng mga alalahanin sa iyong code at paghihiwalay ng code sa mas maliliit na module, klase, at file.

8. Mas madaling maglinis ng kalat kaagad pagkatapos mong gawin kaysa maglinis sa ibang pagkakataon.

Kabanata 15: JUnit Internals

1. Ang mga negatibong variable na pangalan o conditional expression ay medyo mas mahirap maunawaan kaysa sa mga positibo.

2. Ang refactoring ay isang umuulit na proseso na puno ng pagsubok at pagkakamali.

3. Iwanan ang codebase nang mas mahusay kaysa noong nakita mo ito (Boy Scout Rule). (Inulit mula sa Kabanata 1)

Kabanata 16: Refactoring SerialDate

1. Ang mga pagsusuri sa code at pagpuna sa ating code ay nagpapahusay sa atin, at dapat nating tanggapin iyon.

2. Gawin muna ang code, pagkatapos ay ayusin ito.

3. Hindi lahat ng linya ng code ay nangangailangan ng pagsubok.

Kabanata 17: Mga Amoy at Heuristics

1. Ang malinis na code ay hindi isang hanay ng mga panuntunan, ngunit isang sistema ng mga halaga na tumutukoy sa kalidad ng iyong trabaho.

[Sa kabanatang ito, naglista si Uncle Bob ng 66 pang variation ng kanyang code at heuristics, na marami sa mga ito ay tinalakay sa natitirang bahagi ng aklat. Ang pagpaparami ng mga ito dito ay mahalagang pagkopya at pag-paste ng pangalan ng bawat item, kaya pinipigilan kong gawin ito. Iminumungkahi kong basahin mo na lang ang libro!]

Konklusyon

Tapusin natin kung saan tayo nagsimula: Clean Code ni Robert C. Martin ang pinaka-rerekomendang programming book sa lahat ng panahon. May magandang dahilan para dito.