Sepira kerepe sampeyan kudu nggali kode wong liya? Tinimbang rong jam, sampeyan bisa nggunakake rong dina kanggo mung ngerti logika apa sing kedadeyan. Sing lucu yaiku kanggo wong sing nulis kode kasebut, kabeh jelas lan transparan. Iki ora nggumunake: sawise kabeh, kode sampurna minangka konsep sing ora jelas, amarga saben pangembang uga duwe visi dhewe babagan jagad lan kode kasebut. Luwih saka sepisan aku wis ngalami kahanan nalika aku lan kanca kerja ndeleng kode sing padha lan beda panemu babagan bener lan resik.
Muni akrab, ora? Nanging, ana sawetara prinsip sing wis diuji wektu sing kudu ditindakake. Pungkasane, dheweke bakal nguntungake sampeyan, amarga yen sampeyan ninggalake kode sampeyan ing negara sing sampeyan pengin nampa, mula jagad iki bakal dadi luwih seneng lan luwih resik. Ing artikel kita sadurunge(utawa rodo, guide cilik) bab aturan coding, kita tak raos sethitik Rekomendasi kanggo nulis sistem minangka kabèh lan bagean constituent sawijining, kayata obyek, antarmuka, kelas, cara, lan variabel. Ing artikel sing padha, aku nyebutake jeneng unsur tartamtu sing bener. Aku pengin ngomong babagan iki dina iki, amarga jeneng sing bener nggawe kode kasebut luwih gampang diwaca. Kita bakal nutup topik kode sing bener karo sawetara bayangan, conto cilik komentar ing kode, lan pertimbangan apa iki apik utawa ora apik. Inggih, ayo miwiti.
jeneng sing bener
Jeneng sing bener nambah keterbacaan kode, saéngga nyuda wektu sing dibutuhake kanggo ngerti kode kasebut, amarga nggunakake metode luwih gampang nalika jenenge nggambarake fungsine. Kabeh ing kode kasusun saka jeneng (variabel, metode, kelas, obyek, file, etc.), Dadi titik iki dadi penting banget nalika nggawe bener, kode resik. Adhedhasar ing ndhuwur, jeneng kudu menehi makna, contone, kenapa variabel kasebut ana, apa sing ditindakake, lan carane nggunakake. Aku bakal nyathet luwih saka sepisan yen komentar sing paling apik kanggo variabel yaiku menehi jeneng sing apik.
saka TV-seri "Sherlock" (2010-2017)
Jeneng antarmuka
Antarmuka biasane duwe jeneng sing diwiwiti kanthi huruf kapital lan ditulis ing CamelCase. Nalika nulis antarmuka, iku digunakake kanggo dianggep laku apik kanggo nambah ater-ater "I" kanggo nunjukaké minangka antarmuka (contone, IUserService), nanging sing katon cantik elek lan distracting. Ing kasus kaya mengkono, luwih apik kanggo ngilangi awalan (UserService) lan nambah "Impl" minangka seselan kanggo jeneng implementasine (contone UserServiceImpl). Utawa bisa uga, minangka pilihan pungkasan, tambahake ater-ater "C" ing jeneng implementasine (contone CUserService).Jeneng kelas
Kaya antarmuka, jeneng kelas nganggo huruf kapital lan nggunakake CamelCase. Ora Matter yen kita lagi ngadhepi apocalypse zombie, iku ora Matter yen mburi wis ing tangan — tau, tau, jeneng kelas kudu kriya! Jeneng kelas lan obyek kudu nomina utawa tembung majemuk (UserController, UserDetails, UserAccount, lan liya-liyane). Sampeyan ora kudu nyelehake singkatan aplikasi ing mburi jeneng saben kelas, amarga mung bakal nambah kerumitan sing ora perlu. Contone, yen kita duwe aplikasi Migrasi Data pangguna, mula aja nambah "UDM" ing saben kelas, yaiku UDMUserDetails, UDMUserAccount, UDMUserController.Jeneng metode
Biasane, jeneng metode diwiwiti kanthi huruf cilik, nanging uga nggunakake gaya kasus unta (camelCase). Ing ndhuwur, kita ujar manawa jeneng kelas ora kudu dadi kriya. Ing kene kahanane mung kosok balene: jeneng metode kudu kriya utawa frasa kriya: findUserById, findAllUsers, createUser, lan liya-liyane. Nalika nggawe metode (uga variabel lan kelas), gunakake konvensi jeneng sing konsisten supaya ora kebingungan. Contone, kanggo nemokake pangguna, cara bisa dijenengi getUserById utawa findUserById. Lan siji maneh: aja nganggo humor ing jeneng metode, amarga wong liya ora ngerti lelucon kasebut. Akibaté, dheweke bisa uga ora ngerti apa sing ditindakake metode kasebut.Jeneng variabel
Umume kasus, jeneng variabel diwiwiti kanthi huruf cilik lan uga nggunakake camelCase, kajaba variabel kasebut minangka konstanta global. Ing kasus kaya mengkono, kabeh aksara saka jeneng ditulis ing huruf gedhe lan tembung dipisahake dening underscore ("_"). Kanggo penak, sampeyan bisa nggunakake konteks sing migunani nalika menehi jeneng variabel. Ing tembung liyane, nalika variabel ana minangka bagéan saka soko luwih gedhe, contone, jeneng pisanan, jeneng mburi, utawa status. Ing kasus kaya mengkono, sampeyan bisa nambah ater-ater sing nuduhake obyek sing variabel iki belongs. Contone: userFirstName, userLastName, userStatus. Sampeyan uga kudu ngindhari jeneng sing padha kanggo variabel nalika duwe makna sing beda. Ing ngisor iki sawetara antonim sing kerep ditemokake ing jeneng variabel:
- wiwitan / pungkasan
- pisanan / pungkasan
- dikunci / dikunci
- min / maks
- sabanjure / sadurunge
- lawas / anyar
- dibukak / ditutup
- katon / ora katon
- sumber / target
- sumber/tujuan
- munggah mudhun
Jeneng variabel singkat
Nalika kita duwe variabel kaya x utawa n utawa kaya, kita ora langsung weruh maksud wong sing nulis kode kasebut. Iku ora ketok apa n. Ngerteni manawa mbutuhake kontemplasi sing luwih ati-ati (lan iki tegese wektu, wektu, wektu). Contone, umpamane kita duwe lapangan sing nuduhake id pangguna sing tanggung jawab. Tinimbang sawetara jeneng variabel kaya x utawa mung id, kita bakal menehi jeneng variabel iki "responsibleUserId", sing langsung nambah keterbacaan lan isi informasi. Yen ngandika, jeneng cendhak kaya n duwe panggonan minangka variabel lokal ing cara cilik, ngendi pemblokiran kode nglibatno variabel iki mung saperangan saka garis dawa, lan jeneng cara sampurna njlèntrèhaké apa mengkono ana. Ningali variabel kasebut, pangembang ngerti manawa penting banget lan duwe ruang lingkup sing winates. Akibaté, orane katrangan duwe katergantungan tartamtu ing dawa jeneng variabel: jeneng maneh, liyane global variabel lan kosok balene. Minangka conto, iki cara kanggo nemokake pangguna pungkasan sing disimpen miturut tanggal:
public User findLastUser() {
return findAllUsers().stream()
.sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
.findFirst()
.orElseThrow(() -> new ResourceNotFoundException("No user exists"));
}
Dawane optimal
Ayo kita nerusake karo topik dawa jeneng. Dawane jeneng optimal ana ing antarane n lan maximumNumberOfUsersInTheCurrentGroup. Ing tembung liyane, jeneng cendhak nandhang sangsara marga saka lack of makna, nalika jeneng sing dawa banget ndawakake program tanpa nambah readability, lan kita mung kesed kanggo nulis saben wektu. Saliyane kasus sing diterangake ing ndhuwur kanggo variabel kanthi jeneng cendhak kaya n, sampeyan kudu tetep dawane udakara 8-16 karakter. Iki dudu aturan sing ketat, mung pedoman.Bedane cilik
Aku ora bisa gagal kanggo sebutno beda subtle ing jeneng. Iki uga minangka praktik sing ora becik, amarga beda-beda kasebut bisa uga mbingungake utawa mbutuhake wektu ekstra kanggo ngerteni. Contone, prabédan antarane InvalidDataAccessApiUsageException lan InvalidDataAccessResourceUsageException angel ditemokake kanthi cepet. Kebingungan uga bisa asring muncul nalika nggunakake huruf cilik L lan O, amarga padha bisa gampang mistaken kanggo 1 lan 0. Ing sawetara fonts prabédan luwih ketok, ing sawetara iku kurang.Tegese
Kita kudu nggawe jeneng sing migunani, nanging ora nggawe ambiguitas liwat sinonim, amarga, contone, UserData lan UserInfo sejatine duwe makna sing padha. Ing kasus iki, kita kudu digali luwih jero menyang kode kanggo ngerti obyek tartamtu sing kita butuhake. Ngindhari tembung-tembung sing ora menehi informasi sing migunani. Contone, ing firstNameString, kenapa kita butuh tembung String? Apa iki bisa dadi obyek Tanggal? Mesthi ora. Dadi, kita mung nggunakake firstName. Aku uga pengin sebutno variabel boolean. Minangka conto, njupuk boolean jenenge flagDeleted. Tembung gendéra ora duwé teges. Iku luwih cukup kanggo nelpon iku wisDeleted.Disinformasi
Aku uga pengin ngomong sawetara tembung babagan konvensi jeneng sing salah. Ayo kita duwe variabel sing jenenge userActivityList, nanging tinimbang dadi List, obyek iki minangka jinis wadhah liyane utawa obyek panyimpenan khusus. Iki bisa mbingungake programmer rata-rata: luwih becik diarani kaya userActivityGroup utawa userActivities.Nggoleki
Salah sawijining kekurangan saka jeneng sing cendhak lan prasaja yaiku angel ditemokake ing kode gedhe - Sing luwih gampang ditemokake: "jeneng" utawa "NAME_FOR_DEFAULT_USER"? Pilihan kapindho, mesthi. Kita kudu ngindhari tembung (huruf) sing kerep ditemokake ing jeneng, amarga mung bakal nambah jumlah file sing cocog sajrone panelusuran, sing ora apik. Aku pengin ngelingake sampeyan manawa programer luwih akeh wektu maca kode tinimbang nulis, mula dadi pinter babagan menehi jeneng unsur aplikasi sampeyan. Nanging kepiye yen jeneng apik ora bisa ditemokake? Kepiye yen jeneng metode ora nggambarake fungsine kanthi apik? Iki ngendi komentar mlebu panggung.Komentar
Ora ana sing luwih apik tinimbang komentar sing cocog, nanging ora ana sing ngganggu modul kaya komentar kosong, ketinggalan jaman, utawa palsu. Padha bisa dadi pedhang pindho, ora? Nanging, sampeyan ora kudu nganggep komentar minangka apik, nanging minangka ala sing luwih cilik. Sawise kabeh, komentar minangka cara kanggo ngimbangi pamikiran sing ora jelas ing kode kasebut. Contone, kita digunakake kanggo piye wae ngirimake inti saka cara, yen cara dhewe dadi banget bingung. Ing kahanan iki, luwih becik refactor kode kanthi bener tinimbang nulis cathetan deskriptif. Sing lawas komentar, komentar sing luwih elek, amarga kode cenderung tuwuh lan berkembang, nanging komentar bisa uga tetep padha. Luwih akeh wektu sing wis liwati wiwit komentar digawe, luwih bisa dipertanyakan. Komentar sing ora akurat luwih elek tinimbang ora ana komentar, amarga mbingungake lan ngapusi, menehi pangarepan palsu. Lan sanajan kita duwe kode sing angel banget, kita kudu nulis ulang tinimbang menehi komentar.
Jinis komentar
-
Komentar hukum — Komentar ing wiwitan saben file sumber amarga alasan legal, contone:
* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. -
Komentar informatif - Komentar makili panjelasan kode (nyedhiyakake informasi tambahan utawa expounding ing maksud saka bagean tartamtu saka kode).
Tuladhane:
/* * 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() ); }Ing kasus iki, sampeyan bisa nindakake tanpa komentar, amarga jeneng metode lan paramèter, ditambah karo fungsi sing transparan, nggambarake awake dhewe kanthi apik.
-
Komentar bebaya - Komentar sing dimaksudake kanggo ngelingake pangembang liyane babagan akibat sing ora dikarepake saka tumindak (contone, menehi peringatan babagan sebabe tes ditandhani minangka @Ignore):
// Takes too long to run // Don't run if you don't have a lot of time @Ignore @Test public void someIntegrationTest() { …… } -
TODO — Komentar minangka cathetan babagan apa sing kudu ditindakake ing mangsa ngarep, nanging amarga sawetara alasan ora bisa ditindakake saiki. Iki minangka praktik sing apik, nanging komentar kasebut kudu ditinjau kanthi rutin supaya bisa ngilangi sing ora relevan lan ngindhari keruwetan.
Conto bakal dadi:
// 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); }Ing kene kita nyathet kasunyatan manawa kita kudu nambah perbandingan pangguna sing nindakake operasi download (sing ID bakal dijupuk saka konteks keamanan) karo sing nindakake operasi nyimpen.
-
Komentar nguatake - Komentar sing nandheske pentinge kahanan sing sepisanan katon ora pati penting.
Minangka conto, nimbang potongan saka metode sing ngisi database test karo sawetara skrip:
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 -
Komentar Javadoc - Komentar sing nggambarake API kanggo fungsi tartamtu. Mbokmenawa ana komentar sing paling migunani, amarga API sing didokumentasikake luwih gampang digarap. Sing jarene, dheweke uga bisa ketinggalan jaman kaya jinis komentar liyane. Dadi, aja lali manawa kontribusi utama kanggo dokumentasi ora digawe kanthi komentar, nanging kanthi kode sing apik.
Iki conto cara sing cukup umum kanggo nganyari pangguna:
/** * 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);
Komentar ala
-
komentar muttering - Komentar sing biasane ditulis kanthi cepet lan maknane mung bisa dimangerteni dening pangembang sing nulis, amarga mung dheweke sing ngerteni kahanan sing beda-beda ing komentar kasebut.
Coba conto iki:
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 } }Sapa sing mbukak setelan kasebut? Apa padha wis dimuat? Apa cara iki mesthine kanggo nyekel pangecualian lan mbukak setelan gawan? Kakehan pitakonan muncul sing mung bisa dijawab dening delving menyang diselidiki bagean liyane saka sistem.
- Komentar sing berlebihan - Komentar sing ora ngemot semantik, amarga apa sing kedadeyan ing bagean kode kasebut jelas banget. Ing tembung liyane, komentar ora luwih gampang diwaca tinimbang kode.
Ayo ndeleng conto:
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; }Apa gunane komentar kaya ngono? Kabeh sing diterangake wis jelas.
-
Komentar sing ora bisa dipercaya - Komentar sing ora bener lan mung mblusukake (disinformasi). Contone, kene siji.
/** * 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(); }Apa salah karo komentar iki? Kasunyatan sing dumunung kanggo kita sethitik, ing sambungan ditutup yen isNotUsing palsu, ora kosok balene, minangka komentar informs kita.
-
Komentar wajib — Komentar sing dianggep wajib (umpamane komentar Javadoc), nanging nyatane kadhangkala numpuk banget lan ora bisa dipercaya lan ora perlu (sampeyan kudu mikir apa komentar kasebut pancen dibutuhake).
Tuladha:
/**
* 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);
Apa sampeyan bisa ngerti apa cara tanpa komentar kasebut? Paling kamungkinan, ya, supaya komentar dadi ora ana gunane ing kene.
Komentar log - Komentar sing kadhangkala ditambahake ing wiwitan modul saben diowahi (kaya log pangowahan).
/**
* 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;
*/
Pendekatan iki sapisan dibenerake, nanging kanthi tekane sistem kontrol versi (umpamane, Git), dadi keruwetan lan komplikasi kode sing ora perlu.
Komentar pengarang - Komentar sing tujuane kanggo nuduhake wong sing nulis kode kasebut, supaya sampeyan bisa ngubungi dheweke lan ngrembug kepiye, apa, lan kenapa, contone:
* @author Bender Bending
Sawise maneh, sistem kontrol versi ngelingi persis sapa sing nambahake kode lan kapan, mula pendekatan iki ora perlu.
Kode sing dikomentari - Kode sing dikomentari kanthi alasan siji utawa liyane. Iki salah siji saka pakulinan paling awon, amarga apa mengkono iku sampeyan komentar metu soko lan lali, banjur pangembang liyane mung ora duwe wani kanggo mbusak (sawise kabeh, apa yen iku soko terkenal?).
// public void someMethod(SomeObject obj) {
// .....
// }
Akibaté, kode sing dikomentari nglumpukake kaya sampah. Ing kasus apa wae sampeyan kudu ninggalake kode kasebut. Yen pancene mbutuhake, aja lali babagan sistem kontrol versi.
Komentar sing ora jelas - Komentar sing nggambarake soko kanthi cara sing rumit banget.
/*
* 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];
A komentar kudu nerangake kode. Mesthine ora butuh panjelasan. Dadi ana apa ing kene? Apa "saringan byte"? Apa tegese "+ 1"? Kenapa persis 300?
- Gunakake gaya sing gampang dijaga: njaga gaya sing apik banget lan eksotis ngganggu lan butuh wektu.
- Aja nggunakake komentar end-of-line sing nuduhake baris tunggal: asile akeh komentar. Apa maneh, angel mikirake komentar sing migunani kanggo saben baris.
- Nalika sampeyan nulis komentar, coba wangsulan pitakon "kok", dudu "kepiye."
- Ngindhari informasi sing disingkat. Kaya sing dakkandhakake ing ndhuwur, kita ora butuh panjelasan kanggo komentar: komentar kasebut minangka panjelasan.
- Sampeyan bisa nggunakake komentar kanggo nyathet unit lan kisaran nilai.
- Selehake komentar sing cedhak karo kode sing digambarake.
GO TO FULL VERSION