Coffee break #79. 10 pagkakamali ng mga developer ng Java na pumipigil sa kanila sa pagkamit ng tagumpay. Isang Gabay ng Developer sa Pagsulat ng Mga Makabuluhang Komento sa Code

10 Mga Pagkakamali na Ginawa ng Java Developers na Pinipigilan ang Kanilang Tagumpay

Pinagmulan: Dev.to Batay sa aking karanasan, nag-compile ako ng isang listahan ng 10 pagkakamali na ginagawa ng mga developer na pumipigil sa kanila sa pagkamit ng tagumpay:

1. Huwag magsulat ng mga unit test

Ang mga developer na hindi nagsusulat ng mga unit test ay nakakagawa ng mas maraming pagkakamali sa kanilang code. Ito ay humahantong sa kawalang-tatag ng produkto at hindi kasiyahan ng customer.

2. Hindi nila tinitingnan nang manu-mano ang code

Kahit na ganap mong saklawin ang iyong code gamit ang mga unit test, may pagkakataon pa rin na may napalampas ka. Palaging inirerekomenda na manu-manong subukan ang iyong code bago ito isumite para sa pagsusuri. Sa ganitong paraan maaari mong makita ang mga error sa yugto ng pag-unlad.

3. Iniisip nila: "Hinding-hindi ito mangyayari."

Madalas nagkakamali ang mga developer kapag nagsusulat ng bagong code, na iniisip na hindi mangyayari ang ilang partikular na sitwasyon. Sa huli ay lumalabas na mali sila. Pangasiwaan ang lahat ng mga sitwasyon kung saan maaaring isagawa ang code. Ang mga pamamaraan ng pagtatanggol sa programming ay makakatulong sa iyo dito.

4. Huwag makakuha ng feedback

Regular na humingi ng feedback mula sa ibang mga developer at user. Ibahagi ang iyong opinyon sa iyong mga kasamahan.

5. Hindi nila sinusuri ang functionality ng code.

Kadalasan isinusulat ng mga developer ang kanilang code, ngunit huwag suriin ang pag-andar nito. Bilang isang resulta, kapag ang code ay umabot sa produksyon, lumilikha ito ng iba't ibang mga problema.

6. Sumulat ng mahabang procedural code

Napakadaling magsulat ng mahabang pamamaraan na may maraming lohika. Sa paggawa nito, ipinapatupad ng mga programmer ang parehong lohika sa maraming lugar. Ang mga proyektong may malaking bilang ng maliliit na pamamaraan ay may mas mahusay na paggamit muli ng code at mas madaling mapanatili.

7. Hindi nila alam ang mga gamit

Ang mga tool ay extension ng iyong mga kamay. Kung mas kilala mo sila, mas magiging produktibo ka. Dapat ay pamilyar ka sa IDE na iyong ginagamit. Matuto ng mga mabilisang utos, palaging may mga utos na tutulong sa iyo na maging mas produktibo. Sa IntelliJ IDEA ito ay ang Sonar Lint, Spot bug at Code Metrics.

8. Huwag pansinin ang mga problema sa code

Ang mga developer na nagtatrabaho sa pinakamatagumpay na produkto ay patuloy na nagbabago ng code. Huwag matakot na i-refactor ang iyong code. Kung ang iyong code ay nasubok sa yunit, mayroong maliit na pagkakataon ng pagbabalik. Madalas na binabalewala ng mga developer ang may problemang code. Bilang isang developer, responsable ka sa pagpapanatili ng application sa mabuting kondisyon. Para sa kadahilanang ito, ayusin ang anumang mga problemang makikita mo.

9. Nag-code sila nang hindi nalalaman ang mga kahihinatnan.

HINDI dapat gumawa ang mga developer ng mga pagbabago sa code at ilabas ito sa produksyon nang hindi nauunawaan ang mga kahihinatnan. Ang code ay maaaring gumawa ng mga tamang resulta para sa ibinigay na mga halaga ng pagsubok. Gayunpaman, maaaring may mga sitwasyon kung saan maaari itong humantong sa mga hindi mahulaan na resulta at lumikha ng mga seryosong problema. Madalas na nangyayari ang “unpredictable” coding kapag gumagamit ang mga developer ng mga function mula sa mga library na hindi nila lubos na nauunawaan. Maaari rin itong mangyari kapag inayos ng developer ang isang problema nang hindi nauunawaan ang solusyon.

10. Huwag humingi ng tulong

Ang mga developer ay hindi masyadong palakaibigan. Gusto nilang lutasin ang mga problema sa kanilang sarili. Ngunit ang panahon kung kailan ang isang developer mismo ay lumikha ng isang produkto mula simula hanggang matapos ay tapos na. Ang pagbuo ng software ay isang aktibidad ng pangkat. Kapag nakatagpo ka ng problema habang nagprograma, subukang lutasin ito sa iyong sarili. Ngunit huwag mag-aksaya ng maraming oras kung hindi mo mahanap ang solusyon. Malaki ang posibilidad na ang ilan sa iyong mga kasamahan ay nakatagpo na ng parehong problema at alam ang solusyon. Makakatipid ito ng oras at madaragdagan ang pagiging produktibo.

Isang Gabay ng Developer sa Pagsulat ng Mga Makabuluhang Komento sa Code

Source: Stepsize Sa karamihan ng mga kaso, hindi lang ikaw ang nagtatrabaho sa parehong proyekto o codebase. Nangangahulugan ito na dapat maunawaan ng ibang tao ang iyong code. Totoo rin ito para sa mga komento ng code. Ang mga developer ay madalas na nagsusulat ng "mabilis at marumi" na mga komento nang walang gaanong konteksto, na iniiwan ang kanilang mga kasamahan na nalilito tungkol sa kung ano ang sinusubukang sabihin ng may-akda. Ito ay masamang kasanayan at lumilikha ng higit na kalituhan kaysa sa kalinawan. Ang pagkakaroon ng malinaw na mga komento sa code ay nakakatulong sa ibang mga developer. Ang isang komento ng code na naglalarawan ng isang function, ang katwiran nito, input, at output ay nagpapabilis sa proseso ng pag-aaral para sa iba pang mga developer. Sa kabilang banda, ang mga komento ng code ay humahantong sa amin sa tanong: sulit ba itong isulat? Isang makabuluhang pangkat ng mga developer ang tumututol sa pagsulat ng mga komento sa code. Ang dahilan ay ang code, sa kanilang opinyon, ay maliwanag. Kung hindi maintindihan ng isa pang developer ang layunin ng iyong code sa pamamagitan ng pagtingin dito, ito ay masamang code. Marahil ito ay totoo. Ngunit isipin ang tungkol sa maliit na pagsisikap na kinakailangan upang magkomento ng code at ang mga potensyal na benepisyo na dulot nito. Mahalaga ang mga komento sa code para mapabilis ang proseso ng onboarding para sa sinumang developer, lalo na sa mga junior. Tingnan natin ang iba't ibang uri ng mga komento ng code.

1. Mga komento sa dokumentasyon.

Ang pangunahing layunin ng naturang mga komento ay upang mabilis na linawin ang layunin ng isang file o bahagi. Sa halip na basahin ang buong code ng isang bahagi upang maunawaan kung ano ang ginagawa nito, maaari kang magdagdag ng komento ng code sa itaas ng `index` na file. Makakatulong ito na ipaliwanag kung ano ang ginagawa ng bahaging ito. Hindi ako mahilig sa ganitong uri ng komento dahil medyo nakakalat ito sa code. Sa tingin ko ang mga ganitong uri ng mga komento sa arkitektura ay dapat nasa iyong panloob na dokumentasyon kung saan maaari mong sentral na mapanatili at talakayin ang arkitektura ng iyong proyekto. Gayunpaman, kailangan talaga sila ng mga open source na proyekto.

2. Mga komento sa mga function.

Ito ang pinakakapaki-pakinabang na uri ng komento. Inilalarawan nila ang layunin ng function, ang mga parameter nito, at ang output nito.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Lohikal na mga komento.

Ito ay mga komento sa loob ng mga function upang linawin ang mga kumplikadong path ng code. Tulad ng maaaring nahulaan mo, ang pagkakaroon ng mga naturang komento ay nagpapahiwatig na ang iyong code ay masyadong kumplikado. Bilang karagdagan, ang mga lohikal na komento ay kadalasang naglalaman ng napakaraming detalyadong impormasyon. Ang antas ng detalye ay lilikha ng mas maraming kaguluhan at mababawasan ang pagiging madaling mabasa ng iyong code. Narito ang isang halimbawa ng isang sobrang detalyadong komento ng code.

let date = new Date(); // store today's date to calculate the elapsed time

Pagkomento ng Code: 4 Pinakamahuhusay na Kasanayan para sa Pagkomento

1. Gumamit ng mga anotasyon ng code o mga tag

Maraming mga programming language ang tumutukoy sa mga pamantayan para sa code ng pagkomento. Ang Java ay gumagamit ng Javadoc , habang ang JavaScript ay gumagamit ng JSDoc code commenting system , na sinusuportahan ng maraming mga tool sa dokumentasyon. Para sa mga function dapat mong isama ang mga sumusunod na tag ng code:

• @desc - paglalarawan ng iyong function
• @param - lahat ng parameter ng input na tinatanggap ng function. Tiyaking tukuyin ang mga uri ng input.
• @returns - ibinalik ang output. Tiyaking tukuyin ang uri ng output.
• Ang @throws ay ang uri ng error na maaaring ihagis ng function.
• @example - isa o higit pang mga halimbawa na nagpapakita ng input at ang inaasahang output.

Narito ang isang halimbawa ng Lodash code para sa chunk function .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Ipaliwanag ang dahilan ng iyong mga aksyon

Maraming mga developer ang gumagamit ng mga komento upang ilarawan kung ano ang ginagawa ng kanilang code. Kapag ginagawa ito, tiyaking isama kung bakit ka gumawa ng partikular na feature o bahagi. Ang impormasyong ito ay tinatawag na konteksto. Mahalaga ang konteksto upang bigyan ang mga developer ng higit pang impormasyon tungkol sa mga desisyon sa disenyo sa likod ng isang feature o bahagi. Mahalaga ang konteksto kapag gusto ng ibang developer na gumawa ng mga pagbabago sa iyong feature o component. Sa ibaba ay makakakita ka ng masamang halimbawa ng code ng pagkomento nang walang konteksto.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. Huwag mag-link sa ibang mga dokumento o komento

Hindi inirerekomenda na mag-link sa iba pang mga komento sa code o panloob na mga dokumento na nagpapaliwanag ng isang tampok o bahagi.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Sumulat ng mga komento habang nagko-coding

Ito ay maaaring mukhang halata, ngunit maraming mga developer (kasama ako) ang nagpapabaya sa panuntunang ito. Ang pag-iwan ng mga komento para sa ibang pagkakataon ay masama dahil maaaring makalimutan mo ang ilan sa lohika na iyong isinulat, na hahantong sa mas mababang kalidad ng mga komento sa code. Ito ay totoo lalo na kung nagtatrabaho ka sa parehong kahilingan sa paghila sa loob ng ilang araw. Mas mainam na magsulat ng mga komento kapag natapos mo na ang isang feature o module. Tandaan na panatilihing maikli ang mga komento sa code hangga't maaari. Hindi mo kailangang gumugol ng mas maraming oras sa pagsulat ng mga komento kaysa sa pagsulat mo mismo ng code.