కోడింగ్ నియమాలు: సరైన పేర్లు, మంచి మరియు చెడు వ్యాఖ్యల శక్తి

మీరు వేరొకరి కోడ్‌ని ఎంత తరచుగా తవ్వవలసి వచ్చింది? రెండు గంటలకు బదులుగా, ఏమి జరుగుతుందో దాని యొక్క తర్కాన్ని అర్థం చేసుకోవడానికి మీరు రెండు రోజులు గడపవచ్చు. తమాషా ఏమిటంటే, కోడ్ రాసిన వ్యక్తికి, ప్రతిదీ స్పష్టంగా మరియు పూర్తిగా పారదర్శకంగా ఉంటుంది. ఇది ఆశ్చర్యం కలిగించదు: అన్నింటికంటే, ఖచ్చితమైన కోడ్ చాలా అస్పష్టమైన భావన, ఎందుకంటే ప్రతి డెవలపర్‌కు ప్రపంచం మరియు కోడ్ గురించి కూడా స్వంత దృష్టి ఉంటుంది. సహోద్యోగి మరియు నేను ఒకే కోడ్‌ని చూసి దాని ఖచ్చితత్వం మరియు పరిశుభ్రత గురించి భిన్నమైన అభిప్రాయాలను కలిగి ఉన్నప్పుడు నేను ఒకటి కంటే ఎక్కువసార్లు పరిస్థితిని ఎదుర్కొన్నాను.సుపరిచితం అనిపిస్తుంది, కాదా? అయినప్పటికీ, కట్టుబడి ఉండవలసిన కొన్ని సమయ-పరీక్షా సూత్రాలు ఉన్నాయి. చివరికి, అవి మీకు ప్రయోజనకరంగా ఉంటాయి, ఎందుకంటే మీరు మీ కోడ్‌ను స్వీకరించాలనుకుంటున్న స్థితిలో ఉంచినట్లయితే, ప్రపంచం కొద్దిగా సంతోషంగా మరియు శుభ్రంగా మారుతుంది. మా మునుపటి వ్యాసంలో(లేదా బదులుగా, చిన్న గైడ్) కోడింగ్ నియమాల గురించి, సిస్టమ్‌ను మొత్తం మరియు వస్తువులు, ఇంటర్‌ఫేస్‌లు, తరగతులు, పద్ధతులు మరియు వేరియబుల్స్ వంటి దాని భాగాలను వ్రాయడం కోసం మేము కొద్దిగా సిఫార్సులను పొందాము. అదే వ్యాసంలో, కొన్ని అంశాలకు సరైన పేరు పెట్టడాన్ని నేను సాధారణంగా ప్రస్తావించాను. నేను ఈ రోజు దీని గురించి మాట్లాడాలనుకుంటున్నాను, ఎందుకంటే సరైన పేర్లు కోడ్‌ను చదవడానికి చాలా రెట్లు సులభతరం చేస్తాయి. మేము కొన్ని ప్రతిబింబాలు, కోడ్‌లోని వ్యాఖ్యలకు సంబంధించిన చిన్న ఉదాహరణలు మరియు ఇది మంచిదా కాదా అనే పరిశీలనతో సరైన కోడ్ యొక్క అంశాన్ని మూసివేస్తాము. సరే, ప్రారంభిద్దాం.

సరైన పేర్లు

సరైన పేర్లు కోడ్ రీడబిలిటీని మెరుగుపరుస్తాయి, తద్వారా కోడ్‌తో మిమ్మల్ని మీరు పరిచయం చేసుకోవడానికి అవసరమైన సమయాన్ని తగ్గిస్తుంది, ఎందుకంటే దాని పేరు దాని కార్యాచరణను సుమారుగా వివరించినప్పుడు పద్ధతిని ఉపయోగించడం చాలా సులభం. కోడ్‌లోని ప్రతిదీ పేర్లను కలిగి ఉంటుంది (వేరియబుల్స్, పద్ధతులు, తరగతులు, వస్తువులు, ఫైల్‌లు మొదలైనవి), కాబట్టి సరైన, క్లీన్ కోడ్‌ను రూపొందించేటప్పుడు ఈ పాయింట్ చాలా ముఖ్యమైనది. పైన పేర్కొన్నదాని ఆధారంగా, పేరు అర్థాన్ని తెలియజేయాలి, ఉదాహరణకు, వేరియబుల్ ఎందుకు ఉంది, అది ఏమి చేస్తుంది మరియు ఎలా ఉపయోగించబడుతోంది. వేరియబుల్‌కి మంచి పేరు పెట్టడమే ఉత్తమమైన వ్యాఖ్య అని నేను ఒకటి కంటే ఎక్కువసార్లు గమనించాను.

TV-సిరీస్ "షెర్లాక్" (2010-2017) నుండి

నామకరణ ఇంటర్‌ఫేస్‌లు

ఇంటర్‌ఫేస్‌లు సాధారణంగా పెద్ద అక్షరంతో ప్రారంభమయ్యే పేర్లను కలిగి ఉంటాయి మరియు కామెల్‌కేస్‌లో వ్రాయబడతాయి. ఇంటర్‌ఫేస్‌ను వ్రాసేటప్పుడు, దానిని ఇంటర్‌ఫేస్‌గా (ఉదాహరణకు, IUserService) పేర్కొనడానికి "I" ఉపసర్గను జోడించడం మంచి పద్ధతిగా పరిగణించబడుతుంది, కానీ అది చాలా అసహ్యంగా మరియు అపసవ్యంగా కనిపిస్తుంది. అటువంటి సందర్భాలలో, ఉపసర్గ (UserService)ని విస్మరించి, దాని అమలు పేరుకు (ఉదా. UserServiceImpl) ప్రత్యయంగా "Impl"ని జోడించడం మంచిది. లేదా బహుశా, చివరి ప్రయత్నంగా, అమలు పేరుకు "C" ఉపసర్గను జోడించండి (ఉదా CUserService).

తరగతి పేర్లు

ఇంటర్‌ఫేస్‌ల మాదిరిగానే, తరగతి పేర్లు క్యాపిటలైజ్ చేయబడతాయి మరియు CamelCaseని ఉపయోగిస్తాయి. మనం ఒక జోంబీ అపోకలిప్స్‌ని ఎదుర్కొంటున్నా పర్వాలేదు, ముగింపు చేతిలో ఉన్నా పర్వాలేదు — ఎప్పుడూ, ఎప్పుడూ, ఎప్పుడూ తరగతి పేరు క్రియగా ఉండకూడదు! తరగతి మరియు ఆబ్జెక్ట్ పేర్లు తప్పనిసరిగా నామవాచకాలు లేదా సమ్మేళనం నామవాచకాలు (యూజర్‌కంట్రోలర్, యూజర్‌డిటెయిల్స్, యూజర్ ఖాతా మొదలైనవి). మీరు అప్లికేషన్ యొక్క సంక్షిప్తీకరణను ప్రతి తరగతి పేరు చివరలో ఉంచకూడదు, ఎందుకంటే అది అనవసరమైన సంక్లిష్టతను మాత్రమే జోడిస్తుంది. ఉదాహరణకు, మనకు వినియోగదారు డేటా మైగ్రేషన్ అప్లికేషన్ ఉంటే, దయచేసి ప్రతి తరగతికి "UDM"ని జోడించవద్దు, అంటే UDMUserDetails, UDMUserAccount, UDMUserController.

పద్ధతి పేర్లు

సాధారణంగా, పద్ధతి పేర్లు చిన్న అక్షరంతో ప్రారంభమవుతాయి, కానీ అవి ఒంటె కేస్ స్టైల్ (ఒంటెకేస్)ని కూడా ఉపయోగిస్తాయి. పైన, తరగతి పేర్లు ఎప్పుడూ క్రియలు కాకూడదని మేము చెప్పాము. ఇక్కడ పరిస్థితి విరుద్ధంగా ఉంది: పద్ధతుల పేర్లు క్రియలు లేదా క్రియ పదబంధాలుగా ఉండాలి: findUserById, findAllUsers, createUser మరియు మొదలైనవి. ఒక పద్ధతిని సృష్టించేటప్పుడు (అలాగే వేరియబుల్స్ మరియు తరగతులు), కాబట్టి గందరగోళాన్ని నివారించడానికి స్థిరమైన పేరు పెట్టే విధానాన్ని ఉపయోగించండి. ఉదాహరణకు, వినియోగదారుని కనుగొనడానికి, ఒక పద్ధతికి getUserById లేదా findUserById అని పేరు పెట్టవచ్చు. మరియు మరొక విషయం: పద్ధతుల పేర్లలో హాస్యాన్ని ఉపయోగించవద్దు, ఎందుకంటే ఇతరులు తమాషాను అర్థం చేసుకోలేరు. ఫలితంగా, వారు పద్ధతి ఏమి చేస్తుందో గ్రహించడంలో విఫలం కావచ్చు.

వేరియబుల్ పేర్లు

చాలా సందర్భాలలో, వేరియబుల్ గ్లోబల్ స్థిరాంకం అయినప్పుడు తప్ప, వేరియబుల్ పేర్లు చిన్న అక్షరంతో ప్రారంభమవుతాయి మరియు కామెల్‌కేస్‌ను కూడా ఉపయోగిస్తాయి. అటువంటి సందర్భాలలో, పేరులోని అన్ని అక్షరాలు పెద్ద అక్షరంతో వ్రాయబడతాయి మరియు పదాలు అండర్ స్కోర్ ("_") ద్వారా వేరు చేయబడతాయి. సౌలభ్యం కోసం, వేరియబుల్స్ పేరు పెట్టేటప్పుడు మీరు అర్థవంతమైన సందర్భాన్ని ఉపయోగించవచ్చు. మరో మాటలో చెప్పాలంటే, వేరియబుల్ ఏదైనా పెద్ద దానిలో భాగంగా ఉన్నప్పుడు, ఉదాహరణకు, మొదటి పేరు, చివరి పేరు లేదా స్థితి. అటువంటి సందర్భాలలో, మీరు ఈ వేరియబుల్ ఏ వస్తువుకు చెందినదో సూచించే ఉపసర్గను జోడించవచ్చు. ఉదాహరణకు: userFirstName, userLastName, userStatus. వేరియబుల్స్ పూర్తిగా భిన్నమైన అర్థాలను కలిగి ఉన్నప్పుడు మీరు వాటికి సారూప్య పేర్లను కూడా నివారించాలి. వేరియబుల్ పేర్లలో తరచుగా ఉపయోగించే కొన్ని వ్యతిరేక పదాలు ఇక్కడ ఉన్నాయి:

• ప్రారంభం/ముగింపు
• మొదటి చివరి
• లాక్ / అన్‌లాక్ చేయబడింది
• నిమి/గరిష్టంగా
• తదుపరి/మునుపటి
• పాత కొత్త
• తెరవబడింది/మూసివేయబడింది
• కనిపించే / కనిపించని
• మూలం/లక్ష్యం
• మూలం/గమ్యం
• పైకి / క్రిందికి

చిన్న వేరియబుల్ పేర్లు

మనకు x లేదా n వంటి వేరియబుల్స్ లేదా అలాంటిదే ఏదైనా ఉన్నప్పుడు, కోడ్‌ని వ్రాసిన వ్యక్తి యొక్క ఉద్దేశం మనకు వెంటనే కనిపించదు. n ఏమి చేస్తుందో స్పష్టంగా లేదు. దాన్ని గుర్తించడానికి మరింత జాగ్రత్తగా ఆలోచించడం అవసరం (మరియు దీని అర్థం సమయం, సమయం, సమయం). ఉదాహరణకు, బాధ్యతాయుతమైన వినియోగదారు యొక్క idని సూచించే ఫీల్డ్‌ని కలిగి ఉన్నారని అనుకుందాం. x లేదా సింపుల్ ఐడి వంటి కొన్ని వేరియబుల్ పేరుకు బదులుగా, మేము ఈ వేరియబుల్‌కు "రెస్పాన్సిబుల్ యూసర్ఐడి" అని పేరు పెడతాము, ఇది వెంటనే రీడబిలిటీ మరియు ఇన్ఫర్మేషన్ కంటెంట్‌ను మెరుగుపరుస్తుంది. n వంటి సంక్షిప్త పేర్లు చిన్న పద్ధతులలో లోకల్ వేరియబుల్స్‌గా స్థానాన్ని కలిగి ఉంటాయి, ఇక్కడ ఈ వేరియబుల్‌తో కూడిన కోడ్ బ్లాక్ కేవలం రెండు పంక్తుల పొడవు ఉంటుంది మరియు పద్ధతి పేరు అక్కడ ఏమి జరుగుతుందో ఖచ్చితంగా వివరిస్తుంది. అటువంటి వేరియబుల్‌ను చూసినప్పుడు, డెవలపర్ అది ద్వితీయ ప్రాముఖ్యత కలిగి ఉందని మరియు చాలా పరిమిత పరిధిని కలిగి ఉందని అర్థం చేసుకుంటాడు. ఫలితంగా, స్కోప్ ఒక వేరియబుల్ పేరు యొక్క పొడవుపై ఒక నిర్దిష్ట ఆధారపడటాన్ని కలిగి ఉంటుంది: పేరు పొడవుగా ఉంటుంది, వేరియబుల్ మరింత గ్లోబల్ మరియు వైస్ వెర్సా. ఉదాహరణగా, తేదీ వారీగా చివరిగా సేవ్ చేయబడిన వినియోగదారుని కనుగొనడానికి ఇక్కడ ఒక పద్ధతి ఉంది:

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

ఇక్కడ మేము స్ట్రీమ్‌ను క్రమబద్ధీకరించడానికి షార్ట్-నేమ్డ్ వేరియబుల్స్ x మరియు y లను ఉపయోగిస్తాము, ఆపై వాటి గురించి మరచిపోతాము.

సరైన పొడవు

పేరు పొడవు అంశంతో కొనసాగిద్దాం. సరైన పేరు పొడవు n మరియు గరిష్ట సంఖ్యOfUsersInTheCurrentGroup మధ్య ఎక్కడో ఉంటుంది. మరో మాటలో చెప్పాలంటే, చిన్న పేర్లు అర్థం లేకపోవడంతో బాధపడతాయి, అయితే చాలా పొడవుగా ఉన్న పేర్లు చదవగలిగేలా జోడించకుండా ప్రోగ్రామ్‌ను పొడిగిస్తాయి మరియు మేము వాటిని ప్రతిసారీ వ్రాయడానికి చాలా సోమరిపోతాము. n వంటి చిన్న పేరుతో వేరియబుల్స్ కోసం పైన వివరించిన సందర్భంలో కాకుండా, మీరు దాదాపు 8-16 అక్షరాల పొడవుకు కట్టుబడి ఉండాలి. ఇది కఠినమైన నియమం కాదు, కేవలం మార్గదర్శకం.

చిన్న తేడాలు

పేర్లలో సూక్ష్మమైన తేడాలను పేర్కొనకుండా ఉండలేను. ఇది కూడా ఒక చెడ్డ పద్ధతి, ఎందుకంటే ఈ తేడాలు కేవలం గందరగోళంగా ఉండవచ్చు లేదా వాటిని గమనించడానికి ఎక్కువ సమయం వెచ్చించాల్సి ఉంటుంది. ఉదాహరణకు, InvalidDataAccessApiUsageException మరియు InvalidDataAccessResourceUsageException మధ్య వ్యత్యాసాన్ని ఒక్క చూపులో గుర్తించడం కష్టం. చిన్న అక్షరాలు L మరియు Oని ఉపయోగిస్తున్నప్పుడు కూడా తరచుగా గందరగోళం ఏర్పడవచ్చు, ఎందుకంటే అవి 1 మరియు 0గా సులభంగా పొరబడవచ్చు. కొన్ని ఫాంట్‌లలో వ్యత్యాసం మరింత స్పష్టంగా ఉంటుంది, కొన్నింటిలో ఇది తక్కువగా ఉంటుంది.

అర్ధము

మేము పేర్లను అర్ధవంతం చేయాలి, కానీ పర్యాయపదాల ద్వారా అస్పష్టతను సృష్టించకూడదు, ఉదాహరణకు, UserData మరియు UserInfo వాస్తవానికి ఒకే అర్థాన్ని కలిగి ఉంటాయి. ఈ సందర్భంలో, మనకు ఏ నిర్దిష్ట వస్తువు అవసరమో అర్థం చేసుకోవడానికి మేము కోడ్‌ను లోతుగా త్రవ్వాలి. ఉపయోగకరమైన సమాచారాన్ని అందించని పదాలను నివారించండి. ఉదాహరణకు, firstNameStringలో, మనకు స్ట్రింగ్ అనే పదం ఎందుకు అవసరం? ఇది నిజంగా తేదీ వస్తువు అయి ఉండవచ్చా? అస్సలు కానే కాదు. కాబట్టి, మేము కేవలం మొదటి పేరును ఉపయోగిస్తాము. నేను బూలియన్ వేరియబుల్స్ గురించి కూడా చెప్పాలనుకుంటున్నాను. ఉదాహరణగా, ఫ్లాగ్‌డిలీటెడ్ అనే బూలియన్‌ని తీసుకోండి. జెండా అనే పదానికి అర్థం లేదు. దీన్ని తొలగించబడింది అని పిలవడం మరింత సహేతుకమైనది.

తప్పుడు సమాచారం

తప్పు పేరు పెట్టే సంప్రదాయాల గురించి కూడా నేను కొన్ని మాటలు చెప్పాలనుకుంటున్నాను. మన దగ్గర userActivityList అనే వేరియబుల్ ఉందని అనుకుందాం, కానీ జాబితా కాకుండా, ఈ ఆబ్జెక్ట్ కొన్ని ఇతర కంటైనర్ రకం లేదా అనుకూల నిల్వ వస్తువు. ఇది సగటు ప్రోగ్రామర్‌ను గందరగోళానికి గురి చేస్తుంది: దీన్ని userActivityGroup లేదా userActivities వంటిది అని పిలవడం మంచిది.

వెతకండి

చిన్న మరియు సరళమైన పేర్ల యొక్క ప్రతికూలత ఏమిటంటే, అవి పెద్ద సంఖ్యలో కోడ్‌లో కనుగొనడం కష్టం — ఏది సులభంగా కనుగొనవచ్చు: "పేరు" లేదా "NAME_FOR_DEFAULT_USER"? రెండవ ఎంపిక, వాస్తవానికి. పేర్లలో తరచుగా ఎదురయ్యే పదాలను (అక్షరాలను) మనం నివారించాలి, ఎందుకంటే అవి శోధన సమయంలో సరిపోలే ఫైల్‌ల సంఖ్యను మాత్రమే పెంచుతాయి, ఇది మంచిది కాదు. ప్రోగ్రామర్లు కోడ్‌ని వ్రాయడం కంటే చదవడానికి ఎక్కువ సమయం కేటాయిస్తారని నేను మీకు గుర్తు చేయాలనుకుంటున్నాను, కాబట్టి మీ అప్లికేషన్‌లోని అంశాలకు పేరు పెట్టడం గురించి తెలివిగా ఉండండి. అయితే మంచి పేరు రాకపోతే ఎలా? ఒక పద్ధతి పేరు దాని కార్యాచరణను బాగా వివరించకపోతే ఏమి చేయాలి? ఇక్కడే వ్యాఖ్యలు వేదికపైకి వస్తాయి.

వ్యాఖ్యలు

సంబంధిత వ్యాఖ్య కంటే మెరుగైనది ఏదీ లేదు, కానీ శూన్యమైన, కాలం చెల్లిన లేదా తప్పుడు వ్యాఖ్యల వంటి మాడ్యూల్‌ను ఏదీ చిందరవందర చేయదు. అవి రెండంచుల కత్తి కావచ్చు, కాదా? అయినప్పటికీ, మీరు వ్యాఖ్యలను నిస్సందేహంగా మంచిగా పరిగణించకూడదు, బదులుగా తక్కువ చెడుగా పరిగణించాలి. అన్నింటికంటే, కోడ్‌లో స్పష్టంగా రాని ఆలోచనను భర్తీ చేయడానికి వ్యాఖ్య తప్పనిసరిగా ఒక మార్గం. ఉదాహరణకు, పద్ధతి చాలా గందరగోళంగా మారినట్లయితే, ఒక పద్ధతి యొక్క సారాంశాన్ని ఏదో ఒకవిధంగా తెలియజేయడానికి మేము వాటిని ఉపయోగిస్తాము. ఈ పరిస్థితిలో, వివరణాత్మక గమనికలను వ్రాయడం కంటే కోడ్‌ను సరిగ్గా రీఫాక్టర్ చేయడం ఉత్తమం. కామెంట్ ఎంత పెద్దదైతే అంత అధ్వాన్నమైన వ్యాఖ్య, ఎందుకంటే కోడ్ అభివృద్ధి చెందుతుంది మరియు అభివృద్ధి చెందుతుంది, కానీ వ్యాఖ్యలు అలాగే ఉండవచ్చు. వ్యాఖ్య సృష్టించినప్పటి నుండి ఎంత ఎక్కువ సమయం గడిచిందో, అది మరింత సందేహాస్పదంగా ఉండవచ్చు. సరికాని వ్యాఖ్యలు ఎటువంటి వ్యాఖ్యల కంటే చాలా ఘోరంగా ఉంటాయి, ఎందుకంటే అవి గందరగోళంగా మరియు మోసపూరితంగా ఉంటాయి, తప్పుడు అంచనాలను అందిస్తాయి. మరియు మన దగ్గర చాలా గమ్మత్తైన కోడ్ ఉన్నప్పటికీ, మేము దానిని వ్యాఖ్యానించకుండా తిరిగి వ్రాయాలి.

వ్యాఖ్యల రకాలు

• చట్టపరమైన వ్యాఖ్యలు - చట్టపరమైన కారణాల కోసం ప్రతి సోర్స్ ఫైల్ ప్రారంభంలో వ్యాఖ్యలు, ఉదాహరణకు:

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

• ఇన్ఫర్మేటివ్ వ్యాఖ్యలు — కోడ్ యొక్క వివరణను సూచించే వ్యాఖ్యలు (అదనపు సమాచారాన్ని అందించడం లేదా కోడ్ యొక్క ఇచ్చిన విభాగం యొక్క ఉద్దేశ్యాన్ని వివరించడం).

  ఉదాహరణకి:

  
  /*
  * 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()
         );
         }
  

  ఈ సందర్భంలో, మీరు వ్యాఖ్యలు లేకుండా చేయవచ్చు, ఎందుకంటే పద్ధతి యొక్క పేరు మరియు దాని పారామితులు, చాలా పారదర్శక కార్యాచరణతో కలిసి, తమను తాము బాగా వివరిస్తాయి.

• హెచ్చరిక వ్యాఖ్యలు — చర్య యొక్క అవాంఛనీయ పర్యవసానాల గురించి ఇతర డెవలపర్‌లను హెచ్చరించడానికి ఉద్దేశించిన వ్యాఖ్య (ఉదాహరణకు, ఒక పరీక్ష @Ignore అని ఎందుకు గుర్తు పెట్టబడిందనే దాని గురించి వారికి హెచ్చరిక):

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

• TODO - భవిష్యత్తులో చేయవలసిన దాని గురించి గమనిక అయితే కొన్ని కారణాల వల్ల ఇప్పుడు చేయలేము. ఇది మంచి పద్ధతి, కానీ అసంబద్ధమైన వాటిని తీసివేయడానికి మరియు అయోమయానికి దూరంగా ఉండటానికి అటువంటి వ్యాఖ్యలను క్రమం తప్పకుండా సమీక్షించాలి.

  ఒక ఉదాహరణ ఇలా ఉంటుంది:

  
  // 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);
         }
  

  డౌన్‌లోడ్ ఆపరేషన్ చేస్తున్న వినియోగదారుని (భద్రతా సందర్భం నుండి మనం ఎవరి IDని సంగ్రహిస్తాము) సేవ్ ఆపరేషన్ చేసిన వ్యక్తితో పోల్చి చూడాల్సిన అవసరం ఉందని ఇక్కడ మేము గమనించాము.

• బలపరిచే వ్యాఖ్యలు — మొదటి చూపులో చాలా తక్కువగా అనిపించే పరిస్థితి యొక్క ప్రాముఖ్యతను నొక్కి చెప్పే వ్యాఖ్యలు.

  ఉదాహరణగా, కొన్ని స్క్రిప్ట్‌లతో పరీక్ష డేటాబేస్‌ను నింపే పద్ధతి యొక్క భాగాన్ని పరిగణించండి:

  
  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
  

• Javadoc వ్యాఖ్యలు — నిర్దిష్ట కార్యాచరణ కోసం APIని వివరించే వ్యాఖ్యలు. డాక్యుమెంట్ చేయబడిన APIతో పని చేయడం చాలా సులభం కనుక చాలా ఉపయోగకరమైన వ్యాఖ్యలు ఉండవచ్చు. ఇతర రకాల వ్యాఖ్యల మాదిరిగానే అవి కూడా పాతవి కావచ్చని పేర్కొంది. కాబట్టి, డాక్యుమెంటేషన్‌కు ప్రధాన సహకారం వ్యాఖ్యల ద్వారా కాదు, మంచి కోడ్ ద్వారా చేయబడుతుందని ఎప్పటికీ మర్చిపోకండి.

  వినియోగదారుని నవీకరించడానికి చాలా సాధారణ పద్ధతికి ఉదాహరణ ఇక్కడ ఉంది:

  
  /**
  * 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);
  

చెడు వ్యాఖ్యలు

• గొణుగుతున్న వ్యాఖ్య — సాధారణంగా హడావుడిగా వ్రాసే వ్యాఖ్యలు మరియు వాటి అర్థం వాటిని వ్రాసిన డెవలపర్‌కు మాత్రమే అర్థమయ్యేలా ఉంటుంది, ఎందుకంటే వ్యాఖ్య సూచించే సూక్ష్మ పరిస్థితిని అతను లేదా ఆమె మాత్రమే గ్రహిస్తారు.

  ఈ ఉదాహరణను పరిగణించండి:

  
  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 
        }
  }
  

  ఈ సెట్టింగ్‌లను ఎవరు లోడ్ చేస్తారు? అవి ఇప్పటికే లోడ్ అయ్యాయా? ఈ పద్ధతి మినహాయింపులను క్యాచ్ చేసి డిఫాల్ట్ సెట్టింగ్‌లను లోడ్ చేయాలా? సిస్టమ్‌లోని ఇతర భాగాల పరిశోధనను పరిశీలించడం ద్వారా మాత్రమే సమాధానం ఇవ్వగల చాలా ప్రశ్నలు తలెత్తుతాయి.

• పునరావృత వ్యాఖ్యలు — కోడ్‌లోని ఇచ్చిన విభాగంలో ఏమి జరుగుతుందో చాలా స్పష్టంగా ఉన్నందున, ఎటువంటి సెమాంటిక్ లోడ్‌ను కలిగి ఉండని వ్యాఖ్యలు. మరో మాటలో చెప్పాలంటే, కోడ్ కంటే వ్యాఖ్యను చదవడం సులభం కాదు.

  ఒక ఉదాహరణ చూద్దాం:

  
  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;
     }
  

  ఇలాంటి వ్యాఖ్యల వల్ల ప్రయోజనం ఏమిటి? వారు వివరించే ప్రతిదీ ఇప్పటికే స్పష్టంగా ఉంది.

• నమ్మదగని వ్యాఖ్యలు — అవాస్తవమైన మరియు తప్పుదారి పట్టించే వ్యాఖ్యలు (తప్పుడు సమాచారం). ఉదాహరణకు, ఇక్కడ ఒకటి.

  
  /**
  * 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();
  }
  

  ఈ వ్యాఖ్యలో తప్పు ఏమిటి? వ్యాఖ్య మనకు తెలియజేసినట్లుగా, isNotUsing తప్పు అయితే కనెక్షన్ మూసివేయబడిందనే వాస్తవం మాకు కొద్దిగా ఉంది.

• ఆబ్లిగేటరీ కామెంట్‌లు — ఆబ్లిగేటరీ కామెంట్స్ (ఉదా. జావాడోక్ కామెంట్స్), కానీ నిజానికి కొన్నిసార్లు విపరీతంగా పేరుకుపోయి అవి నమ్మదగనివి మరియు అనవసరమైనవి (ఈ వ్యాఖ్యలు నిజంగా అవసరమా కాదా అని మీరు ఆలోచించాలి).

ఉదాహరణ:

/**
* 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);

ఈ వ్యాఖ్యలు లేకుండా పద్ధతి ఏమి చేస్తుందో మీరు అర్థం చేసుకోగలరా? చాలా మటుకు, అవును, కాబట్టి వ్యాఖ్యలు ఇక్కడ అర్ధంలేనివిగా మారతాయి.

• లాగ్ కామెంట్‌లు — మాడ్యూల్‌ని సవరించిన ప్రతిసారీ ప్రారంభానికి జోడించబడే వ్యాఖ్యలు (మార్పు లాగ్ లాంటివి).

  
  /**
  * 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;
  */
  

  ఈ విధానం ఒకసారి సమర్థించబడింది, కానీ సంస్కరణ నియంత్రణ వ్యవస్థల ఆగమనంతో (ఉదాహరణకు, Git), ఇది కోడ్ యొక్క అనవసరమైన అయోమయ మరియు సంక్లిష్టంగా మారింది.

• ఆథర్‌షిప్ వ్యాఖ్యలు — కోడ్‌ను వ్రాసిన వ్యక్తిని సూచించడం ఉద్దేశించిన వ్యాఖ్యలు, కాబట్టి మీరు అతనిని/ఆమెను సంప్రదించవచ్చు మరియు ఎలా, ఏమి మరియు ఎందుకు అనే విషయాలను చర్చించవచ్చు, ఉదా:

  
  * @author Bender Bending
  

  మరోసారి, సంస్కరణ నియంత్రణ వ్యవస్థలు ఎవరు ఏ బిట్ కోడ్‌ను జోడించారో మరియు ఎప్పుడు జోడించారో ఖచ్చితంగా గుర్తుంచుకుంటారు, కాబట్టి ఈ విధానం నిరుపయోగంగా ఉంటుంది.

• వ్యాఖ్యానించిన కోడ్ - ఒక కారణం లేదా మరొక కారణంగా వ్యాఖ్యానించబడిన కోడ్. ఇది చెత్త అలవాట్లలో ఒకటి, ఎందుకంటే మీరు ఏదైనా వ్యాఖ్యానించి, దానిని మరచిపోతారు, ఆపై ఇతర డెవలపర్‌లకు దానిని తొలగించే ధైర్యం లేదు (అన్నింటికంటే, అది విలువైనది అయితే?).

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

  ఫలితంగా, వ్యాఖ్యానించిన కోడ్ ట్రాష్ లాగా పేరుకుపోతుంది. ఎట్టి పరిస్థితుల్లోనూ మీరు అలాంటి కోడ్‌ను వదిలివేయకూడదు. మీకు ఇది నిజంగా అవసరమైతే, సంస్కరణ నియంత్రణ వ్యవస్థ గురించి మర్చిపోవద్దు.

• నాన్-స్పష్టమైన వ్యాఖ్యలు — మితిమీరిన సంక్లిష్టమైన రీతిలో ఏదైనా వివరించే వ్యాఖ్యలు.

  
  /*
      * 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];
  

  ఒక వ్యాఖ్య కోడ్‌ను వివరించాలి. దానికదే వివరణ అవసరం లేదు. కాబట్టి ఇక్కడ తప్పు ఏమిటి? "ఫిల్టర్ బైట్లు" అంటే ఏమిటి? ఆ "+ 1" దేనికి సంబంధించినది? సరిగ్గా 300 ఎందుకు?

మీరు ఇప్పటికే వ్యాఖ్యలు రాయాలని నిర్ణయించుకున్నట్లయితే, ఇక్కడ కొన్ని చిట్కాలు ఉన్నాయి:

1. నిర్వహించడానికి సులభమైన శైలులను ఉపయోగించండి: చాలా ఫాన్సీ మరియు అన్యదేశ శైలులను నిర్వహించడం బాధించేది మరియు సమయం తీసుకుంటుంది.
2. ఒకే పంక్తులను సూచించే ముగింపు-ఆఫ్-లైన్ వ్యాఖ్యలను ఉపయోగించవద్దు: ఫలితంగా పెద్ద సంఖ్యలో కామెంట్‌లు ఉంటాయి. పైగా, ప్రతి పంక్తికి అర్థవంతమైన వ్యాఖ్యను ఆలోచించడం కష్టం.
3. మీరు వ్యాఖ్యను కంపోజ్ చేసినప్పుడు, "ఎలా" అనే ప్రశ్నకు కాకుండా "ఎందుకు" అనే ప్రశ్నకు సమాధానం ఇవ్వడానికి ప్రయత్నించండి.
4. సంక్షిప్త సమాచారాన్ని నివారించండి. నేను పైన చెప్పినట్లుగా, వ్యాఖ్యకు మాకు వివరణ అవసరం లేదు: వ్యాఖ్యే వివరణ.
5. యూనిట్‌లు మరియు విలువ పరిధులను గమనించడానికి మీరు వ్యాఖ్యలను ఉపయోగించవచ్చు.
6. వారు వివరించే కోడ్‌కు దగ్గరగా వ్యాఖ్యలను ఉంచండి.

చివరగా, నేను ఇప్పటికీ మీకు గుర్తు చేయాలనుకుంటున్నాను, ఉత్తమ వ్యాఖ్య కామెంట్ కాదు, మీ అప్లికేషన్ అంతటా నైపుణ్యంతో కూడిన పేరు పెట్టడం. నియమం ప్రకారం, ఎక్కువ సమయం మేము ఇప్పటికే ఉన్న కోడ్‌తో పని చేస్తాము, దానిని నిర్వహించడం మరియు పొడిగించడం. చెడు కోడ్ అడ్డంకిగా ఉన్నందున, ఈ కోడ్ చదవడం సులభం మరియు అర్థమయ్యేలా ఉన్నప్పుడు ఇది చాలా సౌకర్యవంతంగా ఉంటుంది. ఇది పనిలో రెంచ్ విసిరినట్లుగా ఉంటుంది మరియు తొందరపాటు దాని నమ్మకమైన సహచరుడు. మరియు మన దగ్గర ఎంత చెడ్డ కోడ్ ఉంటే అంత పనితీరు పడిపోతుంది. దీని అర్థం మనం ఎప్పటికప్పుడు రీఫాక్టర్ చేయాలి. కానీ మీరు మొదటి నుండి కోడ్‌ని వ్రాయడానికి ప్రయత్నిస్తే, తదుపరి డెవలపర్‌లు మిమ్మల్ని కనుగొని చంపాలని కోరుకోకుండా, మీరు దానిని తరచుగా రీఫాక్టర్ చేయాల్సిన అవసరం లేదు. కొత్త డిపెండెన్సీలు మరియు కనెక్షన్‌ల జోడింపుతో ఉత్పత్తి యొక్క పరిస్థితులు మరియు అవసరాలు నిరంతరం మారుతూ ఉంటాయి కాబట్టి ఇది ఇప్పటికీ అవసరం. సరే, ఈరోజు నాకు అంతే అనుకున్నాను. ఇప్పటివరకు చదివిన ప్రతి ఒక్కరికీ ధన్యవాదాలు :)