Дар мақолаи охирини худ дар бораи қоидаҳои навиштани code (ё дурусттараш, дастури хурд) мо каме ба тавсияҳо оид ба навиштани система дар маҷмӯъ ва унсурҳои он ба монанди an objectҳо, интерфейсҳои онҳо, синфҳо, усулҳо ва тағирёбандаҳо дахл кардем. Дар он чо ман дар бораи дуруст номгузории баъзе унсурхо мухтасар зикр кардам. Имрӯз ман мехоҳам маҳз дар ин бора сӯҳбат кунам, зеро номҳои дуруст хондани codeро хеле осон мекунанд. Мо мавзӯи рамзи дурустро бо ёрии мулоҳизаҳо ва мисолҳои хурди шарҳҳо дар code пӯшида хоҳем кард - ин хуб аст ё на он қадар хуб. Пас биёед оғоз кунем.
Номгузории дуруст
Номҳои дуруст хондани codeро беҳтар мекунанд ва мутаносибан вақтро барои шиносоӣ сарфа мекунанд, зеро истифодаи усуле, ки ном тақрибан фаъолияти онро тавсиф мекунад, хеле осонтар аст. Азбаски ҳама чиз дар code аз номҳо иборат аст (тағйирёбандаҳо, усулҳо, синфҳо, an objectҳои файлӣ ва ғайра), ин нукта ҳангоми эҷоди codeи дуруст ва тоза хеле муҳим мешавад. Бар асоси гуфтаҳои боло, ном бояд маънои онро дошта бошад, ки чаро, масалан, тағирёбанда вуҷуд дорад, чӣ кор мекунад ва чӣ тавр истифода мешавад. Ман такрор ба такрор қайд мекунам, ки беҳтарин шарҳ барои тавсифи тағирёбанда номи дурусти он аст.
Номгузории интерфейсҳо
Интерфейсҳо маъмулан номҳоеро истифода мебаранд, ки бо ҳарфи калон оғоз мешаванд ва дар сурати шутур навишта мешаванд (CamelCase). Ин як таҷрибаи хубе буд, ки ҳангоми навиштани интерфейс бо префикси I он ҳамчун интерфейс таъин карда шавад (масалан, IUserService), аммо ин хеле зишти ва парешон аст. Дар чунин мавридҳо беҳтар аст, ки бидуни он (UserService) нависед ва ба татбиқи он -Impl (UserServiceImpl) илова кунед. Хуб, ё ҳамчун чораи охирин, ба татбиқи он префикси C (CUserService) илова кунед.Номҳои синфҳо
Мисли интерфейсҳо, номҳо бо ҳарфҳои калон навишта мешаванд ва услуби шутурро истифода мебаранд (CamelCase). Новобаста аз он ки чӣ гуна қиёмат рӯй медиҳад, новобаста аз он ки мӯҳлатҳо чӣ қадар тезанд, дар хотир доред, ки номи синф набояд ҳеҷ гоҳ феъл бошад! Номҳои синфҳо ва an objectҳо бояд исмҳо ва таркиби онҳо бошанд (UserController, UserDetails, UserAccount ва ғайра). Шумо набояд номи ҳар як синфро бо ихтисораи ин барнома пешниҳод накунед, зеро ин танҳо мураккабии нолозимро зиёд мекунад (масалан, мо барномаи Муҳоҷирати маълумоти корбар дорем ва мо ба ҳар як синф UDM илова мекунем - UDMUserDeatils, UDMUserAccount, UDMUserController ).Номҳои усулҳо
Одатан номҳои усулҳо бо ҳарфи хурд оғоз мешаванд, аммо онҳо инчунин услуби шутурро (CamelCase) истифода мебаранд. Дар боло мо дар бораи он сухан ронда будем, ки номҳои синфҳо набояд ҳеҷ гоҳ феъл бошанд. Дар ин ҷо вазъият комилан муқобил аст: номҳои усулҳо бояд феълҳо ё таркиби онҳо бо феълҳо бошанд: findUserById, findAllUsers, createUser ва ғайра. Ҳангоми сохтани усул (инчунин тағирёбандаҳо ва синфҳо) барои пешгирӣ кардани иштибоҳ, як равиши номгузориро истифода баред. Масалан, барои пайдо кардани корбар, усулро метавон ҳамчун getUserById ё findUserById навишт. Ва як чизи дигар: дар номҳои усулҳо мазҳакаро истифода набаред, зеро онҳо шӯхро намефаҳманд, инчунин ин усул чӣ кор мекунад.Номҳои тағирёбанда
Дар аксари мавридҳо, номҳои тағирёбанда бо ҳарфи хурд оғоз мешаванд ва инчунин Camelcase -ро истифода мебаранд, ба истиснои ҳолатҳое, ки тағирёбанда доимии глобалӣ аст. Дар ин гуна мавридхо хамаи харфхои ном бо харфхои калон навишта шуда, калимахо бо хатти зер- «_» чудо карда мешаванд. Ҳангоми номгузории тағирёбандаҳо, шумо метавонед контексти пурмазмунро барои роҳат истифода баред. Ба ибораи дигар, вақте ки тағирёбанда ҳамчун ҷузъи чизи калонтар вуҷуд дорад - масалан, Ном, насаб, статус - дар чунин ҳолатҳо шумо метавонед префиксро илова кунед, ки an objectеро, ки ин тағирёбанда ҷузъи он аст, нишон медиҳад. Масалан: userFirstName, userLastName, userStatus. Шумо инчунин бояд аз номҳои шабеҳ барои тағирёбандаҳо канорагирӣ кунед, вақте ки онҳо маънои комилан гуногун доранд. Антонимҳои маъмул барои тағирёбанда:
- оғоз/анҷом
- аввал/охир
- қуфл/қулф
- дақ/макс
- оянда/ гузашта
- кӯҳна/нав
- кушода / баста
- намоён/ноаён
- сарчашма/ҳадаф
- манбаъ/маќсад
- боло поён
Номҳои тағирёбандаи кӯтоҳ
Вақте ки мо тағирёбандаҳоро ба монанди x ё n ё чизе ба ин монанд дорем, мо нияти шахсеро, ки рамз навиштааст, фавран намебинем. Маълум нест, ки усули n чӣ кор мекунад: он тафаккури бештарро талаб мекунад (ва ин вақт, вақт, вақт аст). Масалан, мо майдоне дорем - идентификати корбари масъул ва ба ҷои баъзе номҳо ба монанди x ё танҳо id, мо ин тағирёбандаро масъулиUserId меномем, ки фавран хондан ва пурмазмуниро зиёд мекунад. Аммо, номҳои кӯтоҳ ба монанди n ҷои худро ҳамчун тағироти маҳаллӣ ба усулҳои хурд доранд, ки блоки code бо ин тағирот танҳо якчанд сатри code аст ва номи усул он чизеро, ки дар он ҷо рух медиҳад, комилан тавсиф мекунад. Таҳиягар чунин тағирёбандаро дида, аҳамияти дуюмдараҷа ва доираи хеле маҳдуди онро дарк мекунад. Дар натиҷа, аз дарозии номи тағирёбанда вобастагӣ вуҷуд дорад: ҳар қадар дарозтар бошад, тағирёбанда ҳамон қадар глобалӣ аст ва баръакс. Мисол, усули дарёфти корбари охирини захирашуда аз рӯи сана:public User findLastUser() {
return findAllUsers().stream()
.sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
.findFirst()
.orElseThrow(() -> new ResourceNotFoundException("Any user doesn't exist "));
}Дарозии оптималӣ
Мавзӯи дарозии номро идома медиҳем. Дарозии оптималии ном дар ҷое байни дарозии номи maksimumNumberOfUsersInTheCurrentGroup ва n аст. Яъне, кутоҳҳо аз бемаънӣ ранҷ мекашанд ва аз ҳад дароз барномаро бидуни илова хондан дароз мекунанд ва барои навиштани онҳо ҳар дафъа танбал мешаванд. Бо назардошти ҳолати дар боло зикршуда, барои тағирёбандаҳо бо номи кӯтоҳ ба монанди n, шумо бояд дарозии тақрибан 8 -16 аломатро нигоҳ доред. Ин як қоидаи қатъӣ нест: бештар дастур.Тафовутҳои хурд
Ман наметавонам фарқиятҳои ночизи номҳоро сарфи назар кунам, зеро ин як таҷрибаи бад аст, зеро шумо метавонед танҳо ошуфта шавед ё вақти зиёдеро сарф кунед, то фарқиятҳои ночизи номҳоро мушоҳида кунед. Масалан, фарқияти байни InvalidDataAccessApiUsageException ва InvalidDataAccessResourceUsageExceptionро дар як нигоҳ дидан душвор аст. Инчунин, маълумоти нодуруст ҳангоми истифодаи L ва O хурд аксар вақт пайдо мешавад, зеро онҳоро бо 1 ва 0 ба осонӣ омехта кардан мумкин аст: дар баъзе ҳуруфҳо фарқият равшантар аст, дар дигарҳо камтар.Қисми семантикӣ
Мо бояд қисми семантикиро ба номҳо гузорем, аммо бо синонимҳо зиёд накунем, зеро масалан, UserData ва UserInfo воқеан як маъно доранд ва мо бояд codeро каме амиқтар кобем, то бифаҳмем, ки кадом an objectи мушаххас ба мо лозим аст. . Аз калимаҳои иттилоотӣ худдорӣ намоед, масалан, firstNameString: чаро ба мо калимаи сатр лозим аст? Оё ном метавонад an objectи навъи сана бошад? Албатта не: бинобар ин, танҳо - Номи аввал. Ба сифати мисол, ман мехоҳам тағирёбандаҳои логикиро зикр намоям, масалан, flagDelete. Калимаи парчам маънои семантикиро надорад. Онро номбар кардан оқилонатар мебуд - isDelete.Маълумоти бардурӯғ
Дар бораи нодуруст номгузорй низ чанд сухан гуфтанйам. Фарз мекунем, ки мо номи userActivityList дорем ва an objectе, ки бо чунин ном гузошта шудааст, аз навъи Рӯйхат нест, балки як контейнери дигар ё an objectи фармоишӣ барои нигоҳдорӣ аст. Ин метавонад барномасози миёнаро ба иштибоҳ андозад: беҳтар мебуд, ки онро чизе монанди userActivityGroup ё userActivities номида шавад.Ҷустуҷӯ
Яке аз камбудиҳои номҳои кӯтоҳ ва оддӣ дар он аст, ки онҳоро дар миқдори зиёди code ёфтан душвор аст, зеро пайдо кардани кадоме осонтар хоҳад буд: тағирёбанда бо номи name ё NAME_FOR_DEFAULT_USER? Албатта, варианти дуюм. Дар номҳо аз калимаҳои (ҳарфҳои) зуд-зуд пайдошуда худдорӣ кардан лозим аст, зеро ин танҳо шумораи файлҳои дар вақти ҷустуҷӯ пайдошударо зиёд мекунад, ки ин хуб нест. Хотиррасон менамоем, ки барномасозон нисбат ба навиштани он барои хондани code вақти бештар сарф мекунанд, аз ин рӯ ба номгузории унсурҳои замимаи худ диққат диҳед. Аммо чӣ мешавад, агар шумо онро бомуваффақият номбар карда натавонистед? Чӣ мешавад, агар номи усул функсияи онро хуб тавсиф накунад? Дар ин ҷо он ба бозӣ меояд, ҷузъи навбатии мо шарҳҳост.Шарҳҳо
Ҳеҷ чиз монанди шарҳи мувофиқ вуҷуд надорад, аммо ҳеҷ чиз модулро ба монанди шарҳҳои бемаънӣ, кӯҳна ё гумроҳкунанда халалдор намекунад. Ин шамшери дудама аст, ҳамин тавр не? Бо вуҷуди ин, шумо набояд ба шарҳҳо ҳамчун як некии якхела муносибат кунед: балки ҳамчун як бадии камтар. Баъд аз ҳама, шарҳ, моҳияти худ, ҷуброни андешаи бемуваффақият дар code мебошад. Масалан, мо аз онҳо истифода мебарем, то моҳияти усулро ба таври возеҳ баён кунем, агар он хеле печида бошад. Дар чунин вазъият, беҳтар аст, ки codeро дуруст ислоҳ кунед, на навиштани қайдҳои тавсифӣ. Ҳар қадаре, ки шарҳ калонтар бошад, ҳамон қадар бадтар аст, зеро code майл ба афзоиш ва таҳаввулот дорад, аммо шарҳ метавонад бетағйир боқӣ монад ва ҳар қадаре, ки пеш равад, ин қайдҳо шубҳаноктар мешаванд. Шарҳҳои нодуруст аз бе шарҳ хеле бадтаранд, зеро онҳо иштибоҳ ва фиреб медиҳанд, интизориҳои бардурӯғ медиҳанд. Ва ҳатто агар мо як рамзи хеле душвор дошта бошем ҳам, он ба ҳар ҳол меарзад, ки дар бораи он шарҳ надиҳем, балки онро дубора нависем.
Намудҳои шарҳҳо
-
шарҳҳои ҳуқуқӣ шарҳҳое мебошанд, ки дар аввали ҳар як файли codeи сарчашма бо сабабҳои ҳуқуқӣ боқӣ мондаанд, ба монанди:
* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. -
шарҳҳои иттилоотӣ - шарҳҳое, ки шарҳи codeро пешниҳод мекунанд (пешниҳоди маълумоти иловагӣ ё нияти қисмати додаи code.
Ба унвони мисол:
/* * Объединяет пользователя из бд и пришедшего для обновления * Когда в requestUser поле пустое, оно заполняется старыми данными из 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() ); }Дар ин ҳолат, шумо метавонед бидуни шарҳ кор кунед, зеро номи усул ва далелҳои он, дар якҷоягӣ бо функсияи хеле шаффоф, худро хеле хуб тавсиф мекунанд.
-
шарҳи огоҳкунанда - шарҳе, ки ҳадафи он огоҳ кардани таҳиягарони дигар дар бораи оқибатҳои номатлуби ягон амал аст (масалан, чаро санҷиш ҳамчун @Ignore қайд карда шудааст):
// Слишком долго отрабатывает // Не запускайте, если не располагаете избытком времени @Ignore @Test public void someIntegrationTest() { …… } -
TODO - шарҳҳое, ки барои оянда қайдҳо мебошанд, ки бояд иҷро шаванд, аммо бо баъзе сабабҳо ҳоло иҷро карда намешаванд. Ин як таҷрибаи хуб аст, аммо онҳо ба ҳар ҳол бояд мунтазам аз назар гузаронида шаванд, то шахсони номуносибро аз байн баранд, то аз бесарусомонӣ канорагирӣ кунанд.
Примером послужит:
//TODO: Add a check for the current user ID (when will be created security context) @Override public Resource downloadFile(File file) { return fileManager.download(file); }Тут мы помечаем, что нужно добавить проверку юзера, который скачивает (id которого мы вытащим из security контекста) с тем, кто сохранил.
-
усorвающий комментарий — комментарий, подчеркивающий важность Howого-то обстоятельства, что на первый взгляд может показаться несущественным.
Как пример, кусочек метода, заполняющий тестовую БД, некими скриптами:
Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8) .trim() .split(";")) .forEach(jdbcTemplate::update); // Вызов trim() очень важен, убирает возможные пробелы в конце скрипта // чтобы при считке и разбивке на отдельные requestы не было пустых -
javaDoc — комментарии, которые описывают API определенного функционала для общего пользования. Наверное, самые полезные комментарии, так How с documentированным API в разы легче работать, но они также могут устаревать, How и любые другие. Поэтому не забываем, что главный вклад в documentацию вносится не комментариями, а хорошим codeом.
Пример вполне обычного метода обновления пользователя:
/** * Обновляет передаваемые поля для пользователя по id. * * @param id id обновляемого пользователя * @param user пользователь с заполненными полями для обновления * @return обновленный пользователь */ User update(Long id, User user);
Плохие сценарии комментариев
-
бормочущий комментарий — комментарии, которые обычно пишут на скорую руку, смысл которых понятен только разработчику, писавшего их, так How только он видит ту ситуацию с теми нюансами, на которые он и ссылается.
Рассмотрим данный пример:
public void configureSomeSystem() { try{ String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE); FileInputStream stream = new FileInputStream(configPath); } catch (FileNotFoundException e) { //В случае отсутствия конфигурационного file, загружается конфигурация по умолчанию } }Кто загружает эти настройки? Были ли они загружены ранее? Метод предназначен для перехвата исключений и вызова дефолтных настроек? Слишком много вопросов возникает, ответы на которые можно получить лишь углубившись в изучение других частей системы.
-
избыточный комментарий — комментарий, который не несёт смысловой нагрузки, так How и так понятно что происходит в заданном участке codeа (он читается не проще, чем code).
Смотрим пример:
public class JdbcConnection{ public class JdbcConnection{ /** * Журнальный компонент, связанный с текущим классом */ private Logger log = Logger.getLogger(JdbcConnection.class.getName()); /** * Создаёт и возвращает connection с помощью входящих параметров */ 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; }Какой смысл таких комментариев, если мы и так всё прекрасно видим
-
недостоверные комментарии — комментарии, не соответствующие истине и лишь вгоняющие в заблуждение (дезинформирующие). Как например:
/** * Вспомогательный метод, закрывает соединение со сканером, если isNotUsing истинно */ private void scanClose(Scanner scan, boolean isNotUsing) throws Exception { if (!isNotUsing) { throw new Exception("The scanner is still in use"); } scan.close(); }What в этом комменте не так? А то, что он немножко врёт нам, ведь соединение закрывается, если isNotUsing = false, но ниHow не наоборот, How нам вещает пометка.
-
обязательные комментарии — комментарии, которые считают обязательными (Javadoc), но кои по факту иногда бывают излишне нагромождающими, недостоверными и ненужными (нужно задуматься, а нужны ли здесь такие комментарии).
Пример:
/** * Creation пользователя по переданным параметрам * @param firstName Name созданного пользователя * @param middleName среднее Name созданного пользователя * @param lastName фамorя созданного пользователя * @param age возраст созданного пользователя * @param address addressс созданного пользователя * @return пользователь который был создан */ User createNewUser(String firstName, String middleName, String lastName, String age, String address);Смогли бы вы понять, что делает метод без этих комментариев? Скорее всего да, поэтому комментарии в этом случае стают бессмысленными.
-
журнальные комментарии — комментарии, которые иногда добавляют в начало модуля, при каждом его редактировании (что-то вроде журнала вносимых изменений).
/** * Записи ведутся с 09 января 2020; ********************************************************************** * 09.01.2020 : Обеспечение соединения с БД с помощью Jdbc Connection; * 15.01.2020 : Добавление интерфейсов уровня дао для работы с БД; * 23.01.2020 : Добавление интеграционных тестов для БД; * 28.01.2020 : Имплементация интерфейсов уровня дао; * 01.02.2020 : Разработка интерфейсов для сервисов, * согласно требованиям прописанным в user stories; * 16.02.2020 : Имплементация интерфейсов сервисов * (реализация бизнес логики связанной с работой БД); * 25.02.2020 : Добавление тестов для сервисов; * 08.03.2020 : Празднование восьмого марта(Миша опять в хлам); * 21.03.2020 : Рефакторинг сервис слоя; */Когда-то этот проход был оправдан, но с появлением систем управления исходным codeом (например — Git), это стало лишним нагромождением и усложнением codeа.
-
комментарии ссылки на авторов — комментарии, преднаmeaningм которых является, указание человека, писавшего code, чтобы можно было связаться и обсудить, How что и зачем:
* @author Bender BenderovichОпять же, системы контроля версий прекрасно запоминают, кто и когда добавил данный code, и подобный подход излишен.
-
рамзи шарҳ додашуда codeест, ки бо ин ё он сабаб шарҳ дода шудааст. Яке аз бадтарин одатҳо, зеро шумо онро шарҳ додед ва фаромӯш кардед ва дигар таҳиягарон ҷуръати нест кардани онро надоранд (агар он чизи арзишманд бошад).
// public void someMethod(SomeObject obj) { // ..... // }Дар натиҷа, он мисли партов ҷамъ мешавад. Дар ҳеҷ сурат набояд чунин code гузошта шавад. Агар шумо дар ҳақиқат ба он ниёз доред, дар бораи системаи идоракунии version фаромӯш накунед.
-
шарҳҳои норавшан шарҳҳое мебошанд, ки чизеро ба таври бениҳоят мураккаб тавсиф мекунанд.
/* * Начать с массива, размер которого достаточен для хранения * всех byteов данных (плюс byteы фильтра) с запасом, плюс 300 byte * для данных заголовка */ this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];Шарҳ бояд codeро шарҳ диҳад, на худи тавзеҳот. Дар ин ҷо чӣ гап? "Байтҳои филтрӣ" чистанд? +1 ба ин чӣ иртибот дорад? Чаро маҳз 300?
- Услубҳоеро истифода баред, ки нигоҳ доштанашон осон аст: нигоҳ доштани сабкҳое, ки аз ҳад зебо ва экзотикӣ ҳастанд, метавонад дилгиркунанда ва вақтро талаб кунад.
- Шарҳҳоро дар охири сатрҳо, ки ба як сатр ишора мекунанд, истифода набаред: ин миқдори зиёди шарҳҳоро ба вуҷуд меорад ва барои ҳар як сатр шарҳи пурмазмун пайдо кардан душвор аст.
- Ҳангоми эҷод кардани шарҳ, кӯшиш кунед, ки ба саволи "чаро" ҷавоб диҳед, на "чӣ тавр".
- Аз миёнбурҳо канорагирӣ кунед. Чунон ки дар боло гуфтам, барои шарху эзох ба мо лозим нест: шарху эзох шарх аст.
- Шумо метавонед шарҳҳоро барои қайд кардани воҳидҳои андозагирӣ ва диапазони арзишҳои қобor қабул истифода баред.
- Шарҳҳоро дар наздикии рамзи онҳо ҷойгир кунед.
GO TO FULL VERSION