สรุปโดยย่อของแนวทางปฏิบัติที่ดีที่สุดในการเขียนโค้ด Java

ตามมาตรฐานการเข้ารหัสโดย Oracle, Google, Twitter และ Spring Framework

วัตถุประสงค์ของบทความนี้คือเพื่อให้คุณสรุปอย่างรวดเร็วเกี่ยวกับสิ่งที่ต้องทำและไม่พูดในสิ่งที่ชอบและหลีกเลี่ยงตามมาตรฐานการเข้ารหัสจากยักษ์ใหญ่ด้านเทคโนโลยีเช่น Oracle, Google, Twitter และ Spring Framework

คุณอาจหรืออาจไม่เห็นด้วยกับแนวทางปฏิบัติที่ดีที่สุดบางอย่างที่นำเสนอที่นี่และมันก็ใช้ได้ดีตราบใดที่มีมาตรฐานการเข้ารหัสอยู่

ทำไมมาตรฐานการเข้ารหัสตั้งแต่แรก? มีหลายเหตุผลที่ดีถ้าคุณเป็น Google และฉันจะปล่อยให้คุณมีภาพประกอบต่อไปนี้

เอกสารมาตรฐานการเข้ารหัสอาจมีความยาวและน่าเบื่อ บทความนี้เชอร์รี่เลือกบิตและชิ้นส่วนจากการเข้ารหัสการเข้ารหัสโดย Google, Oracle, Twitter และ Spring และมีวัตถุประสงค์เพื่อให้คุณมีชุดของการปฏิบัติที่ง่ายต่อการติดตามและน่าเบื่อน้อยลงเพื่อให้โค้ดของคุณอ่านและบำรุงรักษาได้ง่าย

เกือบทุกครั้งที่คุณจะเข้าร่วมทีมที่ทำงานกับซอฟต์แวร์ที่มีอยู่และมีโอกาสที่ค่อนข้างดีที่ผู้เขียนส่วนใหญ่ได้ออกหรือเปลี่ยนไปใช้โปรเจ็กต์ต่าง ๆ ทำให้คุณติดกับส่วนของรหัสที่ทำให้คุณตั้งคำถามกับมนุษยชาติ

มาดำดิ่งสู่แนวทางปฏิบัติที่ดีที่สุดจากมาตรฐานการเข้ารหัสที่หลากหลาย

ไฟล์ Java ต้นทาง

ต่อไปนี้ถือเป็นแนวทางปฏิบัติที่ดีที่สุดเมื่อกล่าวถึงซอร์สไฟล์ java:

  • ความยาวไฟล์ต้นฉบับต่ำกว่า 2,000 บรรทัดของรหัส
  • ไฟล์ต้นฉบับจะถูกจัดระเบียบด้วยความคิดเห็นเอกสารประกอบการประกาศแพคเกจตามด้วยความคิดเห็นในชั้นเรียนนำเข้าจัดกลุ่ม (ล่าสุดคงที่) ลายเซ็นคลาส / อินเตอร์เฟซและอื่น ๆ ที่แสดงด้านล่าง
แพ็คเกจ com.example.model;
/ **
 * มุมมองการใช้งานฟรีที่นักพัฒนาจะต้องอ่าน
 * ผู้ที่ไม่จำเป็นต้องมีซอร์สโค้ดอยู่ในมือ
 * * * *
 * @author x, y, z
 * @date
 * @version
 * @copyright
 * * * *
 * /
นำเข้า com.example.util.FileUtil;
/ *
 * ความคิดเห็นเฉพาะชั้นเรียนเสริม
 * * * *
 * /
คลาสสาธารณะบางคลาส {
  // ตัวแปรคงที่ตามลำดับการมองเห็น
  ประชาชนคงสุดท้ายจำนวนเต็ม PUBLIC_COUNT = 1;
  จำนวนเต็มสุดท้ายคงที่ PROTECTED_COUNT = 1;
  จำนวนเต็มคงที่สุดท้ายส่วนตัวของ PRIVATE_COUNT = 1;
  // ตัวแปรอินสแตนซ์ตามลำดับการมองเห็น
  ชื่อสตริงสาธารณะ
  String PostalCode;
  ที่อยู่สตริงส่วนตัว
  // Constructor และโอเวอร์โหลดตามลำดับ
  SomeClass สาธารณะ () {}
  SomeClass สาธารณะ (ชื่อสตริง) {
    this.name = ชื่อ;
  }
  // วิธีการ
  String สาธารณะ doSomethingUseful () {
    คืน "สิ่งที่มีประโยชน์";
  }
  // getters, setters, เท่ากับ, hashCode และ toString ในตอนท้าย
}

การตั้งชื่อ

ชื่อคลาสและส่วนต่อประสานคือ CamelCase และแนะนำให้ใช้ทั้งคำและหลีกเลี่ยงคำย่อ / ตัวย่อ ตัวอย่างเช่นคลาส Raster หรือ ImageSprite คลาส

  • แพ็คเกจ - ชื่อ com.deepspace บน com.deepSpace หรือ com.deep_space
  • ไฟล์ - ชื่อคือ CamelCase และลงท้ายด้วย. java ที่ตรงกับชื่อคลาส มีคลาสพับลิกหนึ่งคลาสต่อหนึ่งไฟล์ที่มีคลาสระดับบนสุดในไฟล์
  • วิธีการ - ชื่อควรจะเป็นคำกริยาในกรณีผสมกับแต่ละคำภายในเป็นตัวพิมพ์ใหญ่เช่น run (); หรือ runFast ();
  • ค่าคงที่ - ควรเป็นตัวพิมพ์ใหญ่ด้วย“ _” คั่นแต่ละคำเช่น int MIN_WIDTH = 44 และ int MAX_WIDTH = 99;
  • Variable - ชื่อที่บอกให้ผู้อ่านโปรแกรมทราบว่าตัวแปรนั้นหมายถึงอะไรเช่นถ้าคุณกำลังเก็บเกรดทดสอบให้เลือก grade vs var1 หลีกเลี่ยงการตั้งชื่อตัวแปรให้สั้นรวมถึงข้อมูลเมตา
// ชอบ () - ชื่อตัวแปรย่อและอธิบายสิ่งที่เก็บไว้
รหัสโรงเรียน
int [] filterSchoolIds;
int [] uniqueSchooldIds;
แผนที่ <จำนวนเต็ม, ผู้ใช้> usersById;
ค่าสตริง;
// เลี่ยง (x) - ตั้งชื่อตัวแปรโดยละเอียดเกินไป
โรงเรียน int หมายเลขประจำตัวประชาชนจำนวน;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
แผนที่ <จำนวนเต็ม, ผู้ใช้> idToUserMap;
ค่าสตริงสตริง;

ข้อควรจำ - ชื่อตัวแปรควรสั้นและง่ายต่อการบอกผู้อ่านว่ามันหมายถึงอะไร ใช้วิจารณญาณของคุณ

ชอบและหลีกเลี่ยง

การจัดรูปแบบและการเยื้องคือทั้งหมดที่เกี่ยวกับการจัดระเบียบรหัสของคุณเพื่อให้ง่ายต่อการอ่านและรวมถึงการเว้นวรรคความยาวบรรทัดการพันและการตัดและอื่น ๆ

  • เยื้อง - ใช้ 2 หรือ 4 ช่องว่างและอยู่อย่างสม่ำเสมอ
  • ความยาวบรรทัด - สูงสุด 70 ถึง 120 อักขระขึ้นอยู่กับผลกระทบต่อความสามารถในการอ่าน สิ่งสำคัญคือการลดความจำเป็นในการเลื่อนแนวนอนและหยุดพักบรรทัดหลังจากเครื่องหมายจุลภาคและโอเปอเรเตอร์

วิธีการ - ต่อไปนี้เป็นรายการแนวทางปฏิบัติที่ดีที่สุด

// ชอบ () การขึ้นบรรทัดใหม่โดยพลการและการแตกหลังจากเครื่องหมายจุลภาค
String downloadAnInternet (อินเทอร์เน็ตอินเทอร์เน็ต, หลอดหลอด,
    Blogosphere บล็อก, จำนวน <ยาว, ข้อมูล> แบนด์วิดท์) {
  tubes.download (อินเทอร์เน็ต);
}
// หลีกเลี่ยง (x) เมธอดยากที่จะแตกต่างกันไปตามส่วนของร่างกาย
String downloadAnInternet (อินเทอร์เน็ตอินเทอร์เน็ต, หลอดหลอด,
    Blogosphere บล็อก, จำนวน <ยาว, ข้อมูล> แบนด์วิดท์) {
    tubes.download (อินเทอร์เน็ต);
}
// ชอบ () เพิ่มช่องว่าง 8 (สองเท่าของ 2 หรือ 4) สำหรับการเยื้องลึก
ส่วนตัวคงที่ตรงกันตรง horkingLongMethodName (int anArg,
        วัตถุอ๊อบเจกต์อื่น, สตริงยังอีกอ
        Object andStillAnother) {
  ...
}
// ชอบ () สแกนอย่างง่ายดายและเพิ่มพื้นที่คอลัมน์
String สาธารณะ downloadAnInternet (
    อินเทอร์เน็ตอินเทอร์เน็ต
    หลอดหลอด
    Blogosphere บล็อก
    จำนวน <ยาว, ข้อมูล> แบนด์วิดท์) {
  tubes.download (อินเทอร์เน็ต);
  ...
}
การทดสอบหน่วยจะพบว่า

If-checks - IMO การเขียนโค้ดที่มีรูปแบบที่ดีทำให้ง่ายต่อการตรวจจับความผิดพลาดและข้อผิดพลาดของผู้เขียนและผู้ตรวจสอบโค้ดดูด้านล่าง:

// หลีกเลี่ยง (x) อย่าละเว้น {}
ถ้า (เงื่อนไข)
  คำให้การ;
// หลีกเลี่ยง (x)
ถ้า (x <0) ลบ (x);
// หลีกเลี่ยง (x)
ถ้า (a == b && c == d) {
...
}
// ชอบ ()
ถ้า ((a == b) && (c == d)) {
...
}
// ชอบ ()
ถ้า (เงื่อนไข) {
  งบ;
} อื่น ๆ หาก (เงื่อนไข) {
  งบ;
} อื่น ๆ หาก (เงื่อนไข) {
  งบ;
}
// หลีกเลี่ยง (x)
ถ้า ((เงื่อนไข 1 && เงื่อนไข 2)
    || (condition3 && condition4)
    ||! (condition5 && condition6)) {// BAD WRAPS
    doSomethingAboutIt (); // ทำให้ LINE นี้ง่ายที่จะพลาด
}
// ชอบ ()
ถ้า ((เงื่อนไข 1 && เงื่อนไข 2)
        || (condition3 && condition4)
        ||! (condition5 && condition6)) {
    doSomethingAboutIt ();
}

ผู้ประกอบการที่ประกอบไปด้วย - และด้านล่างเป็นแนวทางปฏิบัติที่แนะนำ

alpha = (aLongBooleanExpression)? เบต้า: แกมม่า;
alpha = (aLongBooleanExpression)? เบต้า
        : แกมม่า;
alpha = (aLongBooleanExpression)
        ? เบต้า
        : แกมม่า;

สวิตช์ - เมื่อถึงเวลาเปลี่ยนการปฏิบัติที่ดีที่สุดคือ

  • มีตัวพิมพ์เล็กและตัวพิมพ์ใหญ่เสมอแม้ว่าไม่มีรหัส
  • ใช้ / * อยู่ในเครื่องหมาย * / เพื่อระบุว่าตัวควบคุมอยู่ในกรณีถัดไป
สวิตช์ (เงื่อนไข) {
  กรณี ABC:
    งบ;
  / * ผ่าน * /
  กรณี DEF:
    งบ;
    หยุดพัก;
  ค่าเริ่มต้น:
    งบ;
     หยุดพัก;
}

ข้อความข้อยกเว้น - เมื่อส่งข้อยกเว้นนี่คือตัวอย่างข้อความที่ดีและเยื้องไม่ดี

// เลี่ยง (x) - ไม่ใช่เรื่องง่ายที่จะอ่าน
โยน IllegalStateException ใหม่ ("ไม่สามารถดำเนินการตามคำขอ" + request.getId ()
    + "สำหรับผู้ใช้" + user.getId () + "ข้อความค้นหา: '" + query.getText ()
    + "'");
// ชอบ () - อ่านง่ายกว่า
โยน IllegalStateException ใหม่ ("ไม่สามารถดำเนินการ"
    + "คำขอ" + request.getId ()
    + "สำหรับผู้ใช้" + user.getId ()
    + "ข้อความค้นหา: '" + query.getText () + "'");

Iterators and Streams - สตรีมกลายเป็นเรื่องธรรมดามากขึ้นและบางครั้งมันอาจซับซ้อนมากดังนั้นจึงเป็นสิ่งสำคัญที่จะต้องเยื้องเพื่อให้อ่านง่าย

// เลี่ยง (x) - ไม่ใช่เรื่องง่ายที่จะอ่าน
Iterable  modules = ImmutableList.  builder (). เพิ่ม (ใหม่ LifecycleModule ())
    .add (AppLauncherModule ()) ใหม่. addAll (application.getModules ()). build ();
// ชอบ () - อ่านง่ายกว่า
โมดูล  แบบ Iterable = ImmutableList.  ตัวสร้าง ()
    .add (ใหม่ LifecycleModule ())
    .add (AppLauncherModule ใหม่) ()
    .addAll (application.getModules ())
    .สร้าง();
เพียงทำตามมาตรฐานการเข้ารหัส - จริงๆ

การประกาศและการมอบหมาย - แนะนำให้ทำการประกาศหนึ่งรายการต่อบรรทัดเนื่องจากเป็นการส่งเสริมความคิดเห็นดังที่แสดงด้านล่าง

// ชอบ ()
ระดับ int // ระดับการเยื้อง
ขนาด sizeMeter; // ขนาดของตาราง
// หลีกเลี่ยง (x) เพื่อสนับสนุนข้างต้น
ระดับ int, sizeMeter;
// ชอบ () - รวมหน่วยในชื่อตัวแปรหรือประเภท
pollIntervalMs แบบยาว
int fileSizeGb;
จำนวน <จำนวนเต็ม, ข้อมูล> ขนาดไฟล์;
// หลีกเลี่ยง (x) ประเภทการผสม
int foo, fooarray [];
// เลี่ยง (x) - อย่าคั่นด้วยเครื่องหมายจุลภาค
Format.print (System.out,“ ข้อผิดพลาด”), exit (1);
// หลีกเลี่ยง (x) การมอบหมายหลายครั้ง
fooBar.fChar = barFoo.lchar = 'c';
// หลีกเลี่ยง (x) การมอบหมายที่ฝังอยู่ในความพยายามที่จะเพิ่มประสิทธิภาพ // หรือบันทึกบรรทัด ฉันมีความผิดในการทำเช่นนี้ :(
d = (a = b + c) + r;
// ชอบ () มากกว่าด้านบน
a = b + c;
d = a + r;
// ชอบ ()
สตริง [] args
// หลีกเลี่ยง (x)
สตริง args []
// ชอบ () ใช้ "L" แทนการใช้ "l" นาน ๆ เพื่อหลีกเลี่ยงความสับสนกับ 1
หมดเวลานาน = 3000000000L;
// เลี่ยง (x) - ยากที่จะบอกว่าจดหมายฉบับสุดท้ายคือ l และไม่ใช่ 1
หมดเวลานาน = 3000000000l

ใส่การประกาศเฉพาะที่จุดเริ่มต้นของบล็อก (บล็อกคือโค้ดที่ล้อมรอบด้วยเครื่องหมายปีกกา {และ}) อย่ารอที่จะประกาศตัวแปรจนกว่าพวกเขาจะใช้งานครั้งแรก; มันสามารถสร้างความสับสนให้โปรแกรมเมอร์ที่ไม่ระวังและการพกพาโค้ดขัดขวางภายในขอบเขต

// ชอบ () ประกาศที่จุดเริ่มต้นของบล็อก
โมฆะสาธารณะ doSomething () {
  int สิ่งแทนคำพูด; // จุดเริ่มต้นของวิธีการบล็อก
  ถ้า (เงื่อนไข) {
    int someFlag; // จุดเริ่มต้นของบล็อก“ if”
    ...
  }
}

สิ่งสำคัญเช่นกันคือการหลีกเลี่ยงการประกาศในท้องถิ่นที่ซ่อนการประกาศในระดับที่สูงกว่าและเพื่อหลีกเลี่ยงความสับสนดังที่แสดงด้านล่าง

จำนวนนับ
...
โมฆะสาธารณะ doSomething () {
  ถ้า (เงื่อนไข) {
    จำนวนนับ // หลีกเลี่ยง!
    ...
  }
  ...
}

การเว้นวรรค & การแบ่งบรรทัด - หลีกเลี่ยงการล่อลวงของการบันทึกรหัส 1-2 บรรทัดโดยเสียค่าใช้จ่ายในการอ่าน ต่อไปนี้เป็นแนวทางปฏิบัติที่ดีที่สุดเมื่อพูดถึงการเว้นวรรคและบรรทัดว่าง (พื้นที่สีขาวสร้างความแตกต่าง)

  • บรรทัดว่างหนึ่ง (1) บรรทัดระหว่างเมธอดกับผู้พัฒนา Spring แนะนำบรรทัดว่างสอง (2) บรรทัดหลังจากตัวสร้างบล็อกสแตติกฟิลด์และคลาสภายใน
  • ตัวดำเนินการของ Space pad คือใช้ int foo = a + b + 1; มากกว่า int foo = a + b + 1;
  • แยกตัวดำเนินการไบนารีทั้งหมดยกเว้น“.” ออกจากตัวถูกดำเนินการโดยใช้ช่องว่าง
  • วงเล็บปีกกาเปิด“ {” ปรากฏที่ท้ายบรรทัดเดียวกันกับคำสั่งหรือวิธีการประกาศและปิดวงเล็บปีกกา“}” เริ่มต้นบรรทัดด้วยตัวเองเยื้อง
// ชอบ () - เว้นวรรคหลัง "ขณะ" และก่อน "("
ในขณะที่ (จริง) {
  ...
}
// หลีกเลี่ยง (x) - ไม่เหมือนช่องว่างข้างต้น
ในขณะที่ (จริง) {
  ...
}
// ชอบ () - ไม่มีช่องว่างระหว่าง "doSomething" และ "("
โมฆะสาธารณะ doSomething () {
  ...
}
// เลี่ยง (x) - ไม่เหมือนช่องว่างด้านบน
โมฆะสาธารณะ doSomething () {
  ...
}
// ชอบ () - เพิ่มช่องว่างหลังการโต้แย้ง
โมฆะสาธารณะ doSomething (int a, int b) {
  ...
}
// ชอบ () - ช่องว่างระหว่างตัวถูกดำเนินการและตัวดำเนินการ (เช่น +, =)
+ = c + d;
a = (a + b) / (c * d);
ในขณะที่ (d ++ = s ++) {
  n ++;
}

เอกสารและความคิดเห็น

เป็นเรื่องที่ควรค่าแก่การกล่าวถึงว่าเกือบทุกโค้ดจะมีการเปลี่ยนแปลงตลอดอายุการใช้งานและจะมีบางครั้งที่คุณหรือใครบางคนกำลังพยายามที่จะค้นหาว่ากลุ่มของโค้ดวิธีหรือคลาสที่ซับซ้อนนั้นมีวัตถุประสงค์เพื่ออะไร ความเป็นจริงเกือบจะดังต่อไปนี้

มีบางครั้งที่ความคิดเห็นในส่วนที่ซับซ้อนของรหัสวิธีการเรียนไม่ได้เพิ่มมูลค่าใด ๆ หรือให้บริการตามวัตถุประสงค์ มักจะเกิดขึ้นเมื่อแสดงความคิดเห็นเพื่อประโยชน์ของมัน

ความคิดเห็นควรใช้เพื่อให้ภาพรวมของรหัสและให้ข้อมูลเพิ่มเติมที่ไม่พร้อมใช้งานในโค้ดเอง มาเริ่มกันเลย. ความคิดเห็นมีสองประเภท

ความคิดเห็นเกี่ยวกับการติดตั้งใช้งาน - มีไว้เพื่อใส่รหัสหรือแสดงความคิดเห็นเกี่ยวกับการติดตั้งรหัส

ความคิดเห็นจากเอกสาร - มีวัตถุประสงค์เพื่ออธิบายถึงข้อกำหนดของรหัสจากมุมมองที่ปราศจากการนำไปปฏิบัติเพื่อให้นักพัฒนาอ่านซึ่งอาจไม่จำเป็นต้องมีซอร์สโค้ดอยู่ในมือ

บางครั้งความถี่ในการแสดงความคิดเห็นสะท้อนถึงคุณภาพของรหัสที่ไม่ดี เมื่อคุณรู้สึกว่าถูกบังคับให้เพิ่มความคิดเห็นให้ลองเขียนรหัสใหม่เพื่อให้ชัดเจนยิ่งขึ้น

ประเภทของความคิดเห็นในการใช้งาน

ความคิดเห็นเกี่ยวกับการใช้งานมีสี่ (4) ประเภทดังแสดงด้านล่าง

  • บล็อกความคิดเห็น - ดูตัวอย่างด้านล่าง
  • ความคิดเห็นบรรทัดเดียว - เมื่อความคิดเห็นไม่เกินบรรทัด
  • ความคิดเห็นต่อท้าย - ความคิดเห็นสั้นมากถูกย้ายไปที่ท้ายสุด
  • ความคิดเห็นท้ายบรรทัด - เริ่มความคิดเห็นที่ดำเนินต่อไปจนถึงบรรทัดใหม่ มันสามารถคอมเม้นท์ได้ทั้งบรรทัดหรือแค่บางส่วน ไม่ควรใช้ในหลายบรรทัดติดต่อกันเพื่อแสดงความคิดเห็นข้อความ อย่างไรก็ตามสามารถใช้ในหลายบรรทัดติดต่อกันเพื่อแสดงความคิดเห็นส่วนของรหัส
// บล็อกความคิดเห็น
/ *
 * การใช้งาน: ให้คำอธิบายไฟล์วิธีการโครงสร้างข้อมูล
 * และอัลกอริทึม สามารถใช้ที่จุดเริ่มต้นของแต่ละไฟล์และ
 * ก่อนแต่ละวิธี ใช้สำหรับความคิดเห็นที่ยาวที่ไม่เหมาะสม
 * แถวเดียว. 1 บรรทัดว่างเพื่อดำเนินการต่อหลังจากความคิดเห็นบล็อก
 * /
// ความคิดเห็นบรรทัดเดียว
ถ้า (เงื่อนไข) {
 / * จัดการกับสภาพ * /
  ...
}
// ความคิดเห็นต่อท้าย
ถ้า (a == 2) {
 ส่งคืน TRUE /* กรณีพิเศษ */
} อื่น {
 return isPrime (a); / * ทำงานได้เฉพาะกับคี่ * /
}
// ความคิดเห็นท้ายบรรทัด
ถ้า (foo> 1) {
  // ทำสองครั้งที่พลิก
  ...
} อื่น {
  กลับเท็จ // อธิบายว่าทำไมที่นี่
}
// ถ้า (บาร์> 1) {
//
// // ทำแบบพลิกสามครั้ง
// ...
//}
//อื่น
// กลับเท็จ;

ความคิดเห็นเอกสาร (เช่น Javadoc)

Javadoc เป็นเครื่องมือที่สร้างเอกสาร HTML ในรูปแบบโค้ดจาวาของคุณโดยใช้ความคิดเห็นที่ขึ้นต้นด้วย / ** และลงท้ายด้วย * / - ดู Wikipedia สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับวิธีการทำงานของ Javadoc หรืออ่านเพียงอย่างเดียว

นี่คือตัวอย่างของ Javadoc

/ **
 * ส่งคืนออบเจ็กต์รูปภาพที่สามารถทาสีบนหน้าจอได้
 * อาร์กิวเมนต์ url ต้องระบุ {@link URL} แบบสัมบูรณ์ ชื่อ
 * อาร์กิวเมนต์เป็นตัวระบุที่สัมพันธ์กับอาร์กิวเมนต์ url
 * 

 * วิธีนี้จะส่งคืนทันทีเสมอหรือไม่  มีภาพ * อยู่ เมื่อแอปเพล็ตนี้พยายามวาดภาพ  * หน้าจอข้อมูลจะถูกโหลด กราฟิกดั้งเดิม  * ที่วาดภาพจะเพิ่มสีบนหน้าจอ  * * * *  * @param url URL แบบสัมบูรณ์ให้ตำแหน่งฐานของรูปภาพ  * @param ตั้งชื่อตำแหน่งของรูปภาพโดยสัมพันธ์กับอาร์กิวเมนต์ url  * @ คืนรูปภาพที่ URL ที่ระบุ  * @see Image  * /  public Image getImage (URL URL, ชื่อสตริง) {         ลอง {             return getImage (URL ใหม่ (url, ชื่อ));         } catch (MalformedURLException e) {             ส่งคืน null         }  }

และข้างต้นจะส่งผลให้เป็น HTML ดังต่อไปนี้เมื่อ javadoc ทำงานกับรหัสที่มีข้างต้น

ดูที่นี่สำหรับข้อมูลเพิ่มเติม

นี่คือแท็กหลักที่คุณสามารถใช้เพื่อปรับปรุงคุณภาพของเอกสารจาวาที่สร้างขึ้น

@author => @author Raf
@code => {@ รหัส A  C}
@deprecated => @deprecated deprecation-message
@exception => @exception IOException เกิดขึ้นเมื่อ
@link => {@link package.class # ป้ายกำกับสมาชิก}
@param => คำอธิบายพารามิเตอร์ชื่อ @param
@return => วิธีการที่จะส่งกลับ
@see => @see "string" หรือ @see  
@since => เพื่อระบุเวอร์ชันเมื่อมีการเพิ่มวิธีการเข้าถึงแบบสาธารณะ

สำหรับรายการที่สมบูรณ์และคำอธิบายโดยละเอียดเพิ่มเติมดูที่นี่

มาตรฐานการเข้ารหัสของ Twitter แนะนำให้ใช้แท็ก @author

โค้ดสามารถเปลี่ยนมือได้หลายครั้งในช่วงอายุการใช้งานและบ่อยครั้งที่ผู้แต่งดั้งเดิมของไฟล์ต้นฉบับนั้นไม่เกี่ยวข้องหลังจากทำซ้ำหลายครั้ง เราพบว่าควรเชื่อถือประวัติการยอมรับและไฟล์ OWNERS เพื่อตรวจสอบความเป็นเจ้าของรหัสเนื้อหา

ต่อไปนี้เป็นตัวอย่างของวิธีที่คุณสามารถเขียนความคิดเห็นเอกสารที่ลึกซึ้งตามที่อธิบายไว้ในมาตรฐานการเข้ารหัสของ Twitter

// ไม่ดี
// - หมอไม่ได้บอกอะไรเลยว่าวิธีการประกาศนั้นไม่ได้เกิดขึ้น
// - นี่คือ 'สารตัวเติมเอกสาร' มันจะผ่านการตรวจสอบสไตล์ แต่
ไม่ได้ช่วยใครเลย
/ **
 * แบ่งสตริง
 * * * *
 * @param s A สตริง
 * @return รายการของสตริง
 * /
รายการแยก  (String s);
// ดีกว่า
// - เรารู้ว่าวิธีการใดแยก
// - ยังมีพฤติกรรมที่ไม่ได้กำหนด
/ **
 * แบ่งสตริงบนช่องว่าง
 * * * *
 * @param s สตริงที่จะแยก สตริง {@code null} ถือเป็นสตริงว่าง
 * @return รายการของส่วนที่คั่นด้วยช่องว่างของอินพุต
 * /
รายการแยก  (String s);
// เยี่ยมมาก
// - ครอบคลุมอีกกรณีขอบ
/ **
 * แบ่งสตริงบนช่องว่าง อักขระช่องว่างที่ซ้ำกัน
 * ถูกยุบ
 * * * *
 * @param s สตริงที่จะแยก สตริง {@code null} ถือเป็นสตริงว่าง
 * @return รายการของส่วนที่คั่นด้วยช่องว่างของอินพุต
 * /
รายการแยก  (String s);

สิ่งสำคัญคือการเป็นมืออาชีพเมื่อต้องเขียนความคิดเห็น

// หลีกเลี่ยง (x)
// ฉันเกลียด xml / soap มากทำไมมันทำไม่ได้สำหรับฉัน!
ลอง {
  userId = Integer.parseInt (xml.getField ("id"));
} catch (NumberFormatException e) {
  ...
}
// ชอบ ()
// TODO (Jim): การตรวจสอบความถูกต้องของเขตข้อมูลในห้องสมุด
ลอง {
  userId = Integer.parseInt (xml.getField ("id"));
} catch (NumberFormatException e) {
  ...
}

และเป็นสิ่งสำคัญที่ต้องจำไว้ว่าอย่าบันทึกเอกสารวิธีการแทนที่เว้นแต่การเปลี่ยนแปลงนั้นจะมีการเปลี่ยนแปลง

และนี่คือจุดอื่น ๆ ที่ควรทราบ

  • หลีกเลี่ยงการนำเข้าสัญลักษณ์แทน - ตามที่อธิบายไว้ในมาตรฐานการเข้ารหัสของ Twitter ทำให้ที่มาของคลาสไม่ชัดเจน ฉันทำงานเป็นทีมด้วยการผสมผสานของผู้ใช้ Eclipse และ IntelliJ และฉันพบว่า Eclipse จะลบการนำเข้า wildcard และ IntelliJ แนะนำ อาจมีตัวเลือกในการปิดเพียงต้องการชี้ให้เห็นค่าเริ่มต้นสำหรับทั้งสอง
  • ใช้คำอธิบายประกอบ @Override ทุกครั้งเมื่อแทนที่
  • ส่งเสริมให้ใช้ @Nullable เมื่อเขตข้อมูลหรือวิธีการส่งกลับค่า null
  • ใช้ประโยชน์จากความคิดเห็นพิเศษสำหรับงานในอนาคตและอย่าลืมทิ้งการอ้างอิงถึงตัวคุณเองเพื่อให้คนอื่นรู้ว่าใครถามคำถาม Y ของพวกเขาแทนการคาดเดาเอามันออกหรือตรวจสอบความผิด git เพื่อหาผู้ที่เพิ่มเข้ามา IDE บางตัวเช่น Eclipse และ IntelliJ ยังช่วยในการแสดงรายการเหล่านี้เพื่อให้เข้าถึงได้ง่ายเช่นเดียวกับการเตือนความจำ
// FIXME (Raf): ข้อความที่ดำเนินการได้อธิบายถึงสิ่งที่ต้องทำ
// TODO (Raf): ข้อความที่ใช้การได้อธิบายถึงสิ่งที่ต้องทำ

เกมสุดท้ายคือการเขียนโค้ดที่ทำให้ชีวิตของผู้แต่งและผู้ดูแลในอนาคตง่ายขึ้น

จบเกม

วัสดุการอ่านอื่น ๆ ที่เกี่ยวข้อง

รายการของบทความที่เกี่ยวข้องที่เกี่ยวข้องกับการเขียนโค้ดที่สะอาดโครงสร้างดีอ่านง่ายและบำรุงรักษาได้ หากคุณต้องการอ่านเพิ่มเติมขอแนะนำดังต่อไปนี้

และรายการเคล็ดลับการเขียนโค้ดที่ดี