Mga Panuntunan sa Pag-coding: ang Kapangyarihan ng Mga Tamang Pangalan, Mabuti at Masamang Komento

Gaano kadalas mo kinailangan na kumuha ng code ng ibang tao? Sa halip na dalawang oras, maaari kang gumugol ng dalawang araw upang maunawaan lamang ang lohika ng kung ano ang nangyayari. Ang nakakatawang bagay ay para sa taong nagsulat ng code, ang lahat ay malinaw at ganap na transparent. Hindi ito nakakagulat: kung tutuusin, ang perpektong code ay isang napakalabing konsepto, dahil ang bawat developer ay may sariling pananaw sa mundo at sa code, masyadong. Higit sa isang beses ako ay nasa isang sitwasyon nang ang isang katrabaho at ako ay tumingin sa parehong code at magkaiba ang mga opinyon tungkol sa kawastuhan at kalinisan nito.Parang pamilyar, hindi ba? Gayunpaman, may ilang mga prinsipyong nasubok sa panahon na dapat sundin. Sa huli, magiging kapaki-pakinabang sila para sa iyo, dahil kung iiwan mo ang iyong code sa estado kung saan mo mismo gustong matanggap ito, kung gayon ang mundo ay magiging mas masaya at mas malinis. Sa aming nakaraang artikulo(o sa halip, maliit na gabay) tungkol sa mga panuntunan sa coding, nakakuha kami ng kaunting ideya ng mga rekomendasyon para sa pagsusulat ng isang sistema sa kabuuan at ang mga bahaging bumubuo nito, tulad ng mga bagay, interface, klase, pamamaraan, at variable. Sa parehong artikulo, binanggit ko ang tamang pagpapangalan ng ilang mga elemento. Gusto kong pag-usapan ito ngayon, dahil ang mga tamang pangalan ay ginagawang mas madaling basahin ang code nang maraming beses. Isasara namin ang paksa ng tamang code na may ilang mga pagmumuni-muni, maliliit na halimbawa ng mga komento sa code, at isang pagsasaalang-alang kung ito ay mabuti o hindi napakahusay. Well, simulan na natin.

Mga tamang pangalan

Ang mga tamang pangalan ay nagpapabuti sa pagiging madaling mabasa ng code, kaya nababawasan ang oras na kinakailangan upang maging pamilyar sa code, dahil ang paggamit ng isang paraan ay mas madali kapag ang pangalan nito ay halos naglalarawan sa paggana nito. Ang lahat ng nasa code ay binubuo ng mga pangalan (mga variable, pamamaraan, klase, bagay, file, atbp.), kaya ang puntong ito ay nagiging napakahalaga kapag gumagawa ng tama at malinis na code. Batay sa itaas, ang pangalan ay dapat maghatid ng kahulugan, halimbawa, kung bakit umiiral ang variable, ano ang ginagawa nito, at kung paano ito ginagamit. Mapapansin ko nang higit sa isang beses na ang pinakamahusay na komento para sa isang variable ay upang bigyan ito ng isang magandang pangalan.

mula sa TV-serye na "Sherlock" (2010-2017)

Pangalan ng mga interface

Ang mga interface ay karaniwang may mga pangalan na nagsisimula sa malaking titik at nakasulat sa CamelCase. Kapag nagsusulat ng interface, dati ay itinuturing na mabuting kasanayan ang pagdaragdag ng prefix na "I" upang italaga ito bilang isang interface (halimbawa, IUserService), ngunit mukhang pangit at nakakagambala iyon. Sa ganitong mga kaso, mas mabuting alisin ang prefix (UserService) at idagdag ang "Impl" bilang suffix sa pangalan ng pagpapatupad nito (hal. UserServiceImpl). O posibleng, bilang huling paraan, magdagdag ng prefix na "C" sa pangalan ng pagpapatupad (hal. CUserService).

Mga pangalan ng klase

Tulad ng mga interface, ang mga pangalan ng klase ay naka-capitalize at ginagamit ang CamelCase. Hindi mahalaga kung nahaharap tayo sa isang zombie apocalypse, hindi mahalaga kung ang katapusan ay malapit na — hindi kailanman, hindi kailanman, hindi dapat maging isang pandiwa ang pangalan ng isang klase! Ang mga pangalan ng klase at bagay ay dapat na mga pangngalan o tambalang pangngalan (UserController, UserDetails, UserAccount, at iba pa). Hindi mo dapat ilagay ang abbreviation ng application sa dulo ng pangalan ng bawat klase, dahil magdaragdag lang iyon ng hindi kinakailangang kumplikado. Halimbawa, kung mayroon kaming application ng User Data Migration, mangyaring huwag magdagdag ng "UDM" sa bawat klase, ie UDMUserDetails, UDMUserAccount, UDMUserController.

Mga pangalan ng pamamaraan

Karaniwan, ang mga pangalan ng pamamaraan ay nagsisimula sa isang maliit na titik, ngunit gumagamit din sila ng istilo ng camel case (camelCase). Sa itaas, sinabi namin na ang mga pangalan ng klase ay hindi dapat maging pandiwa. Narito ang sitwasyon ay kabaligtaran lamang: ang mga pangalan ng mga pamamaraan ay dapat na mga pandiwa o mga parirala sa pandiwa: findUserById, findAllUsers, createUser, at iba pa. Kapag gumagawa ng paraan (pati na rin ang mga variable at klase), kaya gumamit ng pare-parehong convention sa pagbibigay ng pangalan upang maiwasan ang pagkalito. Halimbawa, para maghanap ng user, maaaring pangalanan ang isang paraan na getUserById o findUserById. At isa pa: huwag gumamit ng katatawanan sa mga pangalan ng mga pamamaraan, dahil maaaring hindi maintindihan ng iba ang biro. Bilang resulta, maaaring hindi nila maunawaan kung ano ang ginagawa ng pamamaraan.

Mga pangalan ng variable

Sa karamihan ng mga kaso, ang mga variable na pangalan ay nagsisimula sa isang maliit na titik at gumagamit din ng camelCase, maliban kung ang variable ay isang global constant. Sa ganitong mga kaso, ang lahat ng mga titik ng pangalan ay nakasulat sa malalaking titik at ang mga salita ay pinaghihiwalay ng isang underscore ("_"). Para sa kaginhawahan, maaari kang gumamit ng makabuluhang konteksto kapag pinangalanan ang mga variable. Sa madaling salita, kapag umiral ang isang variable bilang bahagi ng isang bagay na mas malaki, halimbawa, firstName, lastName, o status. Sa ganitong mga kaso, maaari kang magdagdag ng prefix na nagpapahiwatig ng object kung saan kabilang ang variable na ito. Halimbawa: userFirstName, userLastName, userStatus. Dapat mo ring iwasan ang mga katulad na pangalan para sa mga variable kapag mayroon silang ganap na magkakaibang kahulugan. Narito ang ilang madalas na nakakaharap na mga kasalungat na ginagamit sa mga variable na pangalan:

• simulan/tapos
• Una huli
• naka-lock/naka-unlock
• min/max
• susunod/nakaraan
• lumang bago
• binuksan/sarado
• nakikita/hindi nakikita
• pinagkukunan ng target
• pinagmulan/destinasyon
• taas baba

Mga maikling variable na pangalan

Kapag mayroon tayong mga variable tulad ng x o n o isang katulad nito, hindi natin agad makikita ang layunin ng taong sumulat ng code. Hindi halata ang ginagawa n n. Ang pag-uunawa nito ay nangangailangan ng mas maingat na pagmumuni-muni (at nangangahulugan ito ng oras, oras, oras). Halimbawa, ipagpalagay na mayroon kaming field na kumakatawan sa id ng responsableng user. Sa halip na ilang variable na pangalan tulad ng x o simpleng id, papangalanan namin ang variable na ito na "responsibleUserId", na agad na nagpapahusay sa pagiging madaling mabasa at nilalaman ng impormasyon. Sabi nga, ang mga maiikling pangalan tulad ng n ay may lugar bilang mga lokal na variable sa maliliit na pamamaraan, kung saan ang bloke ng code na kinasasangkutan ng variable na ito ay ilang linya lamang ang haba, at ang pangalan ng pamamaraan ay perpektong naglalarawan kung ano ang nangyayari doon. Nakikita ang gayong variable, nauunawaan ng isang developer na ito ay pangalawang kahalagahan at may napakalimitadong saklaw. Bilang resulta, ang saklaw ay may tiyak na pagdepende sa haba ng isang variable na pangalan: kung mas mahaba ang pangalan, mas global ang variable at vice versa. Bilang halimbawa, narito ang isang paraan upang mahanap ang huling na-save na user ayon sa petsa:

public User findLastUser() {
   return findAllUsers().stream()
           .sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
           .findFirst()
           .orElseThrow(() -> new ResourceNotFoundException("No user exists"));
}

Dito ginagamit namin ang mga variable na may maikling pangalan na x at y upang pag-uri-uriin ang stream, at pagkatapos ay kalimutan namin ang tungkol sa mga ito.

Pinakamainam na haba

Ipagpatuloy natin ang paksa ng haba ng pangalan. Ang pinakamainam na haba ng pangalan ay nasa pagitan ng n at maximumNumberOfUsersInTheCurrentGroup. Sa madaling salita, ang mga maiikling pangalan ay nagdurusa mula sa isang kakulangan ng kahulugan, habang ang mga pangalan na masyadong mahaba ay nagpapahaba ng programa nang hindi nagdaragdag ng pagiging madaling mabasa, at kami ay tamad na isulat ang mga ito sa bawat oras. Bukod sa case na inilarawan sa itaas para sa mga variable na may maikling pangalan tulad ng n, dapat kang manatili sa haba na humigit-kumulang 8-16 na character. Ito ay hindi isang mahigpit na panuntunan, isang gabay lamang.

Maliit na pagkakaiba

Hindi ko mabibigo na banggitin ang mga banayad na pagkakaiba sa mga pangalan. Isa rin itong masamang kagawian, dahil ang mga pagkakaibang ito ay maaaring nakakalito lamang o nangangailangan ng paggugol ng maraming dagdag na oras upang mapansin ang mga ito. Halimbawa, ang pagkakaiba sa pagitan ng InvalidDataAccessApiUsageException at InvalidDataAccessResourceUsageException ay mahirap makita sa isang sulyap. Madalas ding lumitaw ang pagkalito kapag gumagamit ng lowercase na L at O, dahil madali silang mapagkamalang 1 at 0. Sa ilang mga font ay mas halata ang pagkakaiba, sa ilang mga ito ay mas mababa.

Ang kahulugan

Kailangan nating gawing makabuluhan ang mga pangalan, ngunit hindi lumikha ng kalabuan sa pamamagitan ng mga kasingkahulugan, dahil, halimbawa, ang UserData at UserInfo ay talagang may parehong kahulugan. Sa kasong ito, kailangan nating maghukay ng mas malalim sa code upang maunawaan kung aling partikular na bagay ang kailangan natin. Iwasan ang mga salitang hindi nagbibigay ng kapaki-pakinabang na impormasyon. Halimbawa, sa firstNameString, bakit kailangan natin ang salitang String? Talaga bang ito ay isang Date object? Syempre hindi. Kaya, ginagamit lang namin ang firstName. Gusto ko ring banggitin ang mga boolean variable. Bilang halimbawa, kumuha ng boolean na pinangalanang flagDeleted. Walang kahulugan ang salitang bandila. Ito ay mas makatwirang tawaging ito ay Tinanggal.

Disinformation

Gusto ko ring magsabi ng ilang salita tungkol sa maling mga kombensiyon sa pagbibigay ng pangalan. Sabihin nating mayroon kaming variable na pinangalanang userActivityList, ngunit sa halip na maging isang Listahan, ang bagay na ito ay ibang uri ng container o custom na storage object. Maaaring malito nito ang karaniwang programmer: mas mainam na tawagan ito tulad ng userActivityGroup o userActivities.

Maghanap

Ang isa sa mga disbentaha ng maikli at simpleng mga pangalan ay mahirap hanapin ang mga ito sa isang malaking katawan ng code — Alin ang mas madaling mahanap: "pangalan" o "NAME_FOR_DEFAULT_USER"? Ang pangalawang pagpipilian, siyempre. Dapat nating iwasan ang mga madalas na nakakaharap na salita (mga titik) sa mga pangalan, dahil madaragdagan lamang nila ang bilang ng mga tumutugmang file sa panahon ng paghahanap, na hindi maganda. Gusto kong ipaalala sa iyo na ang mga programmer ay gumugugol ng mas maraming oras sa pagbabasa ng code kaysa sa pagsulat nito, kaya maging matalino tungkol sa pagbibigay ng pangalan sa mga elemento ng iyong aplikasyon. Ngunit paano kung ang isang magandang pangalan ay hindi mahanap? Paano kung ang pangalan ng isang pamamaraan ay hindi naglalarawan nang maayos sa paggana nito? Dito pumapasok ang mga komento sa entablado.

Mga komento

Walang mas mahusay kaysa sa isang mahalagang komento, ngunit walang nakakalat sa isang module tulad ng vacuous, lipas na, o maling komento. Maaari silang maging isang tabak na may dalawang talim, hindi ba? Gayunpaman, hindi mo dapat ituring ang mga komento bilang hindi malabo na mabuti, ngunit sa halip bilang isang mas mababang kasamaan. Pagkatapos ng lahat, ang isang komento ay mahalagang paraan upang mabayaran ang pag-iisip na hindi malinaw sa code. Halimbawa, ginagamit namin ang mga ito upang kahit papaano ay ihatid ang kakanyahan ng isang pamamaraan, kung ang pamamaraan mismo ay lumalabas na masyadong nakakalito. Sa sitwasyong ito, mas mahusay na i-refactor nang tama ang code kaysa magsulat ng mga mapaglarawang tala. Kung mas luma ang komento, mas masahol pa ang komento, dahil ang code ay may posibilidad na lumago at nagbabago, ngunit ang mga komento ay maaaring manatiling pareho. Kung mas maraming oras na ang lumipas mula nang gumawa ng komento, mas magiging kaduda-dudang ito. Ang mga hindi tumpak na komento ay mas masahol pa kaysa sa walang komento, dahil ang mga ito ay nakalilito at mapanlinlang, na nagbibigay ng maling mga inaasahan. At kahit na mayroon tayong napakahirap na code, dapat nating isulat muli ito sa halip na magkomento dito.

Mga uri ng komento

• Mga legal na komento — Mga komento sa simula ng bawat source file para sa mga legal na dahilan, halimbawa:

  
  * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  

• Mga komentong nagbibigay-kaalaman — Mga komentong kumakatawan sa paliwanag ng code (nagbibigay ng karagdagang impormasyon o nagpapaliwanag sa intensyon ng isang partikular na seksyon ng code).

  Halimbawa:

  
  /*
  * Combines the user from the database with the one passed for updating
  * When a field in requestUser is empty, it is filled with old data from foundUser
  */
  private User mergeUser(User requestUser, User foundUser) {
         return new User(
         foundUser.getId(),
         requestUser.getFirstName() == null ? requestUser.getFirstName() : foundUser.getFirstName(),
         requestUser.getMiddleName() == null ? requestUser.getMiddleName() : foundUser.getMiddleName(),
         requestUser.getLastName() == null ? requestUser.getLastName() : foundUser.getLastName(),
         requestUser.getAge() == null ? requestUser.getAge() : foundUser.getAge()
         );
         }
  

  Sa kasong ito, maaari mong gawin nang walang mga komento, dahil ang pangalan ng pamamaraan at mga parameter nito, kasama ng napaka-transparent na pag-andar, ay mahusay na naglalarawan sa kanilang sarili.

• Mga komento sa babala — Ang komento ay nilayon upang balaan ang ibang mga developer tungkol sa mga hindi kanais-nais na kahihinatnan ng isang aksyon (halimbawa, babala sa kanila kung bakit minarkahan ang isang pagsubok bilang @Ignore):

  
  // Takes too long to run
  // Don't run if you don't have a lot of time
  @Ignore
  @Test
  public void someIntegrationTest() {
         ……
         }
  

• TODO — Mga komento na isang tala tungkol sa isang bagay na kailangang gawin sa hinaharap na ngunit sa ilang kadahilanan ay hindi magawa ngayon. Ito ay isang magandang kasanayan, ngunit ang mga naturang komento ay dapat na regular na suriin upang maalis ang mga hindi nauugnay at maiwasan ang mga kalat.

  Ang isang halimbawa ay:

  
  // TODO: Add a check for the current user ID (when the security context is created)
  
  @Override
  public Resource downloadFile(File file) {
         return fileManager.download(file);
         }
  

  Dito napapansin namin ang katotohanan na kailangan naming magdagdag ng paghahambing ng user na nagsasagawa ng operasyon sa pag-download (na ang ID ay kukunin namin mula sa konteksto ng seguridad) sa isa na nagsagawa ng operasyon sa pag-save.

• Pagpapatibay ng mga komento — Mga komentong nagbibigay-diin sa kahalagahan ng isang pangyayari na sa unang tingin ay tila hindi gaanong mahalaga.

  Bilang halimbawa, isaalang-alang ang isang piraso ng isang paraan na pumupuno sa isang pagsubok na database ng ilang mga script:

  
  Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8)
         .trim()
         .split(";"))
         .forEach(jdbcTemplate::update);
  // The trim() call is very important. It removes possible spaces at the end of the script
  // so that when we read and split into separate requests, we don't end up with empty ones
  

• Mga komento sa Javadoc — Mga komentong naglalarawan sa API para sa ilang partikular na pagpapagana. Marahil ay may mga pinakakapaki-pakinabang na komento, dahil mas madaling gamitin ang dokumentadong API. Iyon ay sinabi, maaari rin silang maging lipas na tulad ng anumang iba pang uri ng komento. Kaya, huwag kalimutan na ang pangunahing kontribusyon sa dokumentasyon ay ginawa hindi sa pamamagitan ng mga komento, ngunit sa pamamagitan ng mahusay na code.

  Narito ang isang halimbawa ng isang medyo karaniwang paraan para sa pag-update ng isang user:

  
  /**
  * Updates the passed fields for a user based on its id.
       *
  * @param id id of the user to be updated
  * @param user user with populated fields for updating
  * @return updated user
  */
         User update(Long id, User user);
  

Masamang komento

• muttering comment — Mga komentong kadalasang isinusulat nang nagmamadali at ang kahulugan ay nauunawaan lamang ng developer na sumulat nito, dahil tanging siya lang ang nakakaunawa ng nuanced na sitwasyon na tinutukoy ng komento.

  Isaalang-alang ang halimbawang ito:

  
  public void configureSomeSystem() {
         try{
         String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE);
         FileInputStream stream = new FileInputStream(configPath);
         } catch (FileNotFoundException e) {
         // If there is no configuration file, the default configuration is loaded 
        }
  }
  

  Sino ang naglo-load ng mga setting na ito? Na-load na ba sila? Ang paraang ito ba ay dapat na makakuha ng mga pagbubukod at mag-load ng mga default na setting? Napakaraming tanong ang lumitaw na masasagot lamang sa pamamagitan ng pagsisiyasat sa ibang bahagi ng system.

• Mga paulit-ulit na komento — Mga komentong hindi nagdadala ng anumang semantic load, dahil malinaw na malinaw ang nangyayari sa isang partikular na seksyon ng code. Sa madaling salita, ang komento ay hindi mas madaling basahin kaysa sa code.

  Tingnan natin ang isang halimbawa:

  
  public class JdbcConnection{
  public class JdbcConnection{
     /**
      * The logger associated with the current class
      */
     private Logger log = Logger.getLogger(JdbcConnection.class.getName());
  
     /**
      * Creates and returns a connection using the input parameters
      */
     public static Connection buildConnection(String url, String login, String password, String driver) throws Exception {
         Class.forName(driver);
         connection = DriverManager.getConnection(url, login, password);
         log.info("Created connection with db");
         return connection;
     }
  

  Ano ang silbi ng mga ganyang komento? Lahat ng ipinapaliwanag nila ay ganap na malinaw.

• Mga komentong hindi mapagkakatiwalaan — Mga komentong hindi totoo at nakakapanlinlang lamang (disinformation). Halimbawa, narito ang isa.

  
  /**
  * Helper method. Closes the connection with the scanner if isNotUsing is true
  */
  private void scanClose(Scanner scan, boolean isNotUsing) throws Exception {
     if (!isNotUsing) {
         throw new Exception("The scanner is still in use");
     } scan.close();
  }
  

  Ano ang mali sa komentong ito? Ang katotohanan na ito ay namamalagi sa amin ng kaunti, sa na ang koneksyon ay sarado kung isNotUsing ay hindi totoo, hindi vice versa, bilang ang komento ay nagpapaalam sa amin.

• Obligatoryong mga komento — Mga komentong itinuturing na obligado (hal. Javadoc na mga komento), ngunit sa katunayan ay nakatambak nang sobra-sobra at hindi mapagkakatiwalaan at hindi kailangan (kailangan mong pag-isipan kung talagang kailangan ang mga komentong ito).

Halimbawa:

/**
* Create a user based on the parameters
* @param firstName first name of the created user
* @param middleName middle name of the created user
* @param lastName last name of the created user
* @param age age of the created user
* @param address address of the created user
* @return user that was created
*/
User createNewUser(String firstName, String middleName, String lastName, String age, String address);

Mauunawaan mo ba kung ano ang ginagawa ng pamamaraan nang wala ang mga komentong ito? Malamang, oo, kaya nagiging walang kabuluhan ang mga komento dito.

• Mga komento sa log — Mga komento na minsan ay idinaragdag sa simula ng isang module sa tuwing ito ay na-edit (tulad ng isang log ng pagbabago).

  
  /**
  * Records kept since January 9, 2020;
  **********************************************************************
  * 9 Jan 2020: Providing a database connection using JDBC Connection;
  * 15 Jan 2020: Adding DAO-level interfaces for working with the database;
  * 23 Jan 2020: Adding integration tests for the database;
  * 28 Jan 2020: Implementation of DAO-level interfaces;
  * 1 Feb 2020: Development of interfaces for services,
  * in accordance with the requirements specified in user stories;
  * 16 Feb 2020: Implementation of service interfaces
  * (implementation of business logic related to the work of the database);
  * 25 Feb 2020: Adding tests for services;
  * 8 Mar 2020: Celebration of International Women's Day (Terry is drunk again);
  * 21 Mar 2020: Refactoring the service layer;
  */
  

  Ang pamamaraang ito ay dating nabigyang-katwiran, ngunit sa pagdating ng mga sistema ng kontrol ng bersyon (halimbawa, Git), ito ay naging isang hindi kinakailangang kalat at komplikasyon ng code.

• Mga komento sa may-akda — Mga komento na ang layunin ay ipahiwatig ang taong nagsulat ng code, para makontak mo siya at talakayin kung paano, ano, at bakit, hal:

  
  * @author Bender Bending
  

  Muli, eksaktong natatandaan ng mga system control ng bersyon kung sino ang nagdagdag ng anumang bit ng code at kung kailan, kaya hindi kailangan ang diskarteng ito.

• Commented-out code — Code na na-comment out para sa isang kadahilanan o iba pa. Ito ang isa sa mga pinakamasamang ugali, dahil ang mangyayari ay nagkomento ka ng isang bagay at nakalimutan mo ito, at pagkatapos ay ang ibang mga developer ay walang lakas ng loob na tanggalin ito (pagkatapos ng lahat, paano kung ito ay isang bagay na mahalaga?).

  
  //    public void someMethod(SomeObject obj) {
  //    .....
  //    }
  

  Bilang resulta, naiipon ang na-comment na code na parang basura. Sa anumang kaso dapat mong iwanan ang naturang code. Kung talagang kailangan mo ito, huwag kalimutan ang tungkol sa version control system.

• Mga komentong hindi halata — Mga komentong naglalarawan ng isang bagay sa sobrang kumplikadong paraan.

  
  /*
      * Start with an array large enough to store
      * all the data bytes (plus filter bytes) with a cushion, plus 300 bytes
      * for header data
      */
  this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];
  

  Dapat ipaliwanag ng isang komento ang code. Ito mismo ay hindi nangangailangan ng paliwanag. Kaya ano ang mali dito? Ano ang "filter bytes"? Ano ang ibig sabihin ng "+ 1" na iyon? Bakit eksaktong 300?

Kung nagpasya ka nang magsulat ng mga komento, narito ang ilang tip:

1. Gumamit ng mga istilong madaling mapanatili: ang pagpapanatili ng mga istilong masyadong magarbong at kakaiba ay nakakainis at nakakaubos ng oras.
2. Huwag gumamit ng mga komento sa dulo ng linya na tumutukoy sa mga solong linya: ang resulta ay isang malaking tumpok ng mga komento. Higit pa rito, mahirap mag-isip ng makabuluhang komento para sa bawat linya.
3. Kapag gumawa ka ng komento, subukang sagutin ang tanong na "bakit", hindi "paano."
4. Iwasan ang pinaikling impormasyon. Tulad ng sinabi ko sa itaas, hindi namin kailangan ng paliwanag para sa isang komento: ang komento mismo ay ang paliwanag.
5. Maaari kang gumamit ng mga komento upang itala ang mga unit at hanay ng halaga.
6. Maglagay ng mga komento malapit sa code na inilalarawan nila.

Sa wakas, gusto ko pa ring ipaalala sa iyo na ang pinakamahusay na komento ay walang komento, ngunit sa halip ay ang paggamit ng mahusay na pagpapangalan sa kabuuan ng iyong aplikasyon. Bilang isang patakaran, kadalasan ay gagana kami sa umiiral na code, pinapanatili at palawigin ito. Ito ay mas maginhawa kapag ang code na ito ay madaling basahin at naiintindihan, dahil ang masamang code ay isang balakid. Ito ay tulad ng paghahagis ng isang wrench sa mga gawa, at pagmamadali ang kanyang tapat na kasama. At ang mas masamang code na mayroon tayo, mas maraming bumababa ang pagganap. Nangangahulugan ito na kailangan nating mag-refactor paminsan-minsan. Ngunit kung sa simula ay susubukan mong magsulat ng code na hindi magiging sanhi ng pagnanais ng mga susunod na developer na hanapin at patayin ka, hindi mo na kakailanganing i-refactor ito nang madalas. Ngunit ito ay kinakailangan pa rin, dahil ang mga kondisyon at kinakailangan ng produkto ay patuloy na nagbabago sa pagdaragdag ng mga bagong dependency at koneksyon. Well, I guess that's all for me today. Salamat sa lahat ng nagbabasa hanggang dito :)