ปรับปรุงการตรวจสอบโค้ดด้วยหมายเหตุ

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

คำอธิบายประกอบช่วยให้คุณระบุคำแนะนำแก่เครื่องมือตรวจสอบโค้ด เช่น Lint เพื่อช่วยตรวจหาปัญหาโค้ดที่ละเอียดอ่อนมากขึ้นเหล่านี้ได้ ระบบจะเพิ่มคำอธิบายประกอบเป็นแท็กข้อมูลเมตาที่คุณแนบกับตัวแปร พารามิเตอร์ และค่าที่แสดงผลเพื่อตรวจสอบค่าที่แสดงผลของเมธอด พารามิเตอร์ที่ส่ง ตัวแปรในเครื่อง และฟิลด์ เมื่อใช้กับเครื่องมือตรวจสอบโค้ด คำอธิบายประกอบจะช่วยให้คุณตรวจพบปัญหาต่างๆ เช่น null pointer exception และความขัดแย้งของประเภททรัพยากร

Android รองรับคำอธิบายประกอบที่หลากหลายผ่านไลบรารีคำอธิบายประกอบ Jetpack คุณเข้าถึงไลบรารีได้ผ่านแพ็กเกจ androidx.annotation

หมายเหตุ: หากโมดูลมีทรัพยากร Dependency ในโปรเซสเซอร์สำหรับคำอธิบายประกอบ คุณต้องใช้การกำหนดค่าทรัพยากร Dependency kapt หรือ ksp สำหรับ Kotlin หรือการกำหนดค่าทรัพยากร Dependency annotationProcessor สำหรับ Java เพื่อเพิ่มทรัพยากร Dependency นั้น

เพิ่มคำอธิบายประกอบลงในโปรเจ็กต์

หากต้องการเปิดใช้คำอธิบายประกอบในโปรเจ็กต์ ให้เพิ่มทรัพยากร Dependency androidx.annotation:annotation ลงในไลบรารีหรือแอป ระบบจะตรวจสอบคำอธิบายประกอบที่คุณเพิ่มเมื่อคุณเรียกใช้การตรวจสอบโค้ดหรืองาน lint

เพิ่มทรัพยากร Dependency ของไลบรารี Jetpack Annotations

ไลบรารีคำอธิบายประกอบ Jetpack เผยแพร่อยู่ในที่เก็บ Maven ของ Google หากต้องการเพิ่มไลบรารี Jetpack Annotations ลงในโปรเจ็กต์ ให้ใส่บรรทัดต่อไปนี้ในบล็อก dependencies ของไฟล์ build.gradle หรือ build.gradle.kts

Kotlin

dependencies {
    implementation("androidx.annotation:annotation:1.11.0")
}

ดึงดูด

dependencies {
    implementation 'androidx.annotation:annotation:1.11.0'
}
จากนั้นคลิกซิงค์เลยในแถบเครื่องมือหรือการแจ้งเตือนการซิงค์ที่ปรากฏขึ้น

หากคุณใช้คำอธิบายประกอบในโมดูลไลบรารีของคุณเอง ระบบจะรวมคำอธิบายประกอบไว้เป็นส่วนหนึ่งของอาร์ติแฟกต์ Android Archive (AAR) ในรูปแบบ XML ในไฟล์ annotations.zip การเพิ่มทรัพยากร Dependency androidx.annotation จะไม่ทำให้เกิดทรัพยากร Dependency สำหรับผู้ใช้ปลายทางของไลบรารี

หมายเหตุ: หากใช้ไลบรารี Jetpack อื่นๆ คุณอาจไม่จำเป็นต้องเพิ่มทรัพยากร Dependency androidx.annotation เนื่องจากไลบรารี Jetpack อื่นๆ จำนวนมากขึ้นอยู่กับไลบรารีคำอธิบายประกอบ คุณจึงอาจมีสิทธิ์เข้าถึงคำอธิบายประกอบอยู่แล้ว

ดูรายการคำอธิบายประกอบทั้งหมดที่รวมอยู่ในที่เก็บ Jetpack ได้ที่ข้อมูลอ้างอิงไลบรารีคำอธิบายประกอบ Jetpack หรือใช้ฟีเจอร์เติมข้อความอัตโนมัติเพื่อแสดงตัวเลือกที่ใช้ได้สำหรับคำสั่ง import androidx.annotation.

เรียกใช้การตรวจสอบโค้ด

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

นอกจากนี้ คุณยังบังคับใช้คำอธิบายประกอบได้โดยเรียกใช้งาน lint โดยใช้บรรทัดคำสั่ง แม้ว่าวิธีนี้อาจเป็นประโยชน์ในการแจ้งปัญหาเกี่ยวกับเซิร์ฟเวอร์การรวมอย่างต่อเนื่อง แต่งาน lint จะไม่บังคับใช้คำอธิบายประกอบ Nullness (อธิบายไว้ในส่วนถัดไป) มีเพียง Android Studio เท่านั้นที่ทำเช่นนี้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการเปิดใช้และการตรวจสอบ Lint ได้ที่การปรับปรุงโค้ดด้วยการตรวจสอบ Lint

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

คำอธิบายประกอบ Nullness

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

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

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

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

// ...
/** Annotation not used because of the safe-call operator(?)**/
override fun onCreateView(
    name: String,
    context: Context,
    attrs: AttributeSet
): View? {
    // ...
}
// ...

การวิเคราะห์ความสามารถในการเป็นค่า Null

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

  • การเรียกใช้เมธอดที่แสดงผลเป็น Null ได้
  • เมธอดที่ไม่ควรแสดงผลเป็น Null
  • ตัวแปร เช่น ฟิลด์ ตัวแปรในเครื่อง และพารามิเตอร์ ที่อาจเป็น Null ได้
  • ตัวแปร เช่น ฟิลด์ ตัวแปรเฉพาะที่ และพารามิเตอร์ ที่ไม่สามารถเก็บค่า Null ได้

จากนั้นการวิเคราะห์จะแทรกคำอธิบายประกอบ Null ที่เหมาะสมในตำแหน่งที่ตรวจพบโดยอัตโนมัติ

หากต้องการเรียกใช้การวิเคราะห์ความสามารถในการเป็นค่า Null ใน Android Studio ให้เลือกวิเคราะห์ > อนุมานค่า Null Android Studio จะแทรกคำอธิบายประกอบ Android @Nullable และ @NonNull ในตำแหน่งที่ตรวจพบในโค้ดของคุณ หลังจากเรียกใช้การวิเคราะห์ค่า Null แล้ว แนวทางปฏิบัติแนะนำคือการยืนยันคำอธิบายประกอบที่แทรก

หมายเหตุ: เมื่อเพิ่มคำอธิบายประกอบค่า Null การเติมข้อความอัตโนมัติอาจแนะนำคำอธิบายประกอบ @Nullable และ @NotNull ของ IntelliJ แทนคำอธิบายประกอบค่า Null ของ Android และอาจนำเข้าไลบรารีที่เกี่ยวข้องโดยอัตโนมัติ อย่างไรก็ตาม เครื่องมือวิเคราะห์ซอร์สโค้ดของ Android Studio จะมองหาเฉพาะคำอธิบายประกอบค่า Null ของ Android เท่านั้น เมื่อยืนยันคำอธิบายประกอบ ให้ตรวจสอบว่าโปรเจ็กต์ใช้คำอธิบายประกอบ Android Null เพื่อให้เครื่องมือตรวจสอบ Lint แจ้งเตือนคุณได้อย่างถูกต้องในระหว่างการตรวจสอบโค้ด

คำอธิบายประกอบทรัพยากร

การตรวจสอบประเภททรัพยากรมีประโยชน์เนื่องจากการอ้างอิงทรัพยากรของ Android เช่น ทรัพยากร drawable และ ทรัพยากรสตริง string จะส่งเป็นจำนวนเต็ม

โค้ดที่คาดหวังพารามิเตอร์เพื่ออ้างอิงทรัพยากรประเภทที่เฉพาะเจาะจง เช่น String สามารถส่งไปยังประเภทข้อมูลอ้างอิงที่คาดหวังของ int ได้ แต่อันที่จริงแล้วจะอ้างอิงทรัพยากรประเภทอื่น เช่น ทรัพยากร R.string

ตัวอย่างเช่น เพิ่มคำอธิบายประกอบ @StringRes เพื่อตรวจสอบว่าพารามิเตอร์ทรัพยากรมีการอ้างอิง R.string หรือไม่ ดังที่แสดงที่นี่

abstract fun setTitle(@StringRes resId: Int)

ในระหว่างการตรวจสอบโค้ด คำอธิบายประกอบจะสร้างคำเตือนหากไม่มีการส่งการอ้างอิง R.string ในพารามิเตอร์

คุณสามารถเพิ่มคำอธิบายประกอบสำหรับทรัพยากรประเภทอื่นๆ เช่น @DrawableRes, @DimenRes, @ColorRes และ @InterpolatorRes ได้โดยใช้รูปแบบคำอธิบายประกอบเดียวกันและเรียกใช้ระหว่างการตรวจสอบโค้ด

หากพารามิเตอร์รองรับประเภททรัพยากรหลายประเภท คุณสามารถใส่คำอธิบายประกอบประเภททรัพยากรมากกว่า 1 รายการในพารามิเตอร์ที่กำหนดได้ ใช้ @AnyRes เพื่อระบุว่าพารามิเตอร์ที่มีคำอธิบายประกอบสามารถเป็นทรัพยากร R ประเภทใดก็ได้

แม้ว่าคุณจะใช้ @ColorRes เพื่อระบุว่าพารามิเตอร์ควรเป็นทรัพยากรสีได้ แต่ระบบจะไม่รู้จักจำนวนเต็มสี (ในรูปแบบ RRGGBB หรือ AARRGGBB) เป็นทรัพยากรสี แต่ให้ใช้คำอธิบายประกอบ @ColorInt เพื่อระบุว่าพารามิเตอร์ต้องเป็นจำนวนเต็มสีแทน เครื่องมือสร้างจะแจ้งโค้ดที่ไม่ถูกต้องซึ่งส่งรหัสทรัพยากรสี เช่น android.R.color.black ไปยังเมธอดที่มีคำอธิบายประกอบ แทนที่จะเป็นจำนวนเต็มสี

คำอธิบายประกอบชุดข้อความ

คำอธิบายประกอบเทรดจะตรวจสอบว่ามีการเรียกใช้เมธอดจากเทรดประเภทใดประเภทหนึ่งหรือไม่ ระบบรองรับคำอธิบายประกอบชุดข้อความต่อไปนี้

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

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

การใช้คำอธิบายประกอบชุดข้อความที่พบบ่อยคือการตรวจสอบว่าเมธอดหรือคลาสที่มีคำอธิบายประกอบ @WorkerThread มีการเรียกใช้จากชุดข้อความที่ทำงานอยู่เบื้องหลังที่เหมาะสมเท่านั้น

คำอธิบายประกอบข้อจำกัดของค่า

ใช้คำอธิบายประกอบ @IntRange, @FloatRange และ @Size เพื่อตรวจสอบค่าของพารามิเตอร์ที่ส่งมา ทั้ง @IntRange และ @FloatRange จะมีประโยชน์มากที่สุดเมื่อใช้กับพารามิเตอร์ที่ผู้ใช้มีแนวโน้มที่จะระบุช่วงผิด

คำอธิบายประกอบ @IntRange จะตรวจสอบว่าค่าพารามิเตอร์จำนวนเต็มหรือแบบยาวอยู่ภายในช่วงที่ระบุ ตัวอย่างต่อไปนี้แสดงให้เห็นว่าพารามิเตอร์ alpha ต้องมีค่าจำนวนเต็มตั้งแต่ 0 ถึง 255

fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) {
    // ...
}

คำอธิบายประกอบ @FloatRange จะตรวจสอบว่าค่าพารามิเตอร์ Float หรือ Double อยู่ในช่วงค่าจุดลอยตัวที่ระบุหรือไม่ ตัวอย่างต่อไปนี้ระบุว่าพารามิเตอร์ alpha ต้องมีค่าจำนวนจริงตั้งแต่ 0.0 ถึง 1.0

fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {
    // ...
}

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

  • ขนาดขั้นต่ำ เช่น @Size(min=2)
  • ขนาดสูงสุด เช่น @Size(max=2)
  • ขนาดที่แน่นอน เช่น @Size(2)
  • ตัวเลขที่ขนาดต้องเป็นจำนวนเท่า เช่น @Size(multiple=2)

ตัวอย่างเช่น @Size(min=1) จะตรวจสอบว่าคอลเล็กชันไม่ว่างเปล่า และ @Size(3) จะตรวจสอบว่าอาร์เรย์มีค่า 3 ค่าพอดี

ตัวอย่างต่อไปนี้แสดงให้เห็นว่าอาร์เรย์ location ต้องมีองค์ประกอบอย่างน้อย 1 รายการ

fun getLocation(button: View, @Size(min = 1) location: IntArray) {
    button.getLocationOnScreen(location)
}

คำอธิบายประกอบสิทธิ์

ใช้คำอธิบายประกอบ @RequiresPermission เพื่อตรวจสอบสิทธิ์ของผู้เรียกใช้เมธอด หากต้องการตรวจสอบสิทธิ์เดียวจากรายการสิทธิ์ที่ถูกต้อง ให้ใช้แอตทริบิวต์ anyOf หากต้องการตรวจสอบชุดสิทธิ์ ให้ใช้แอตทริบิวต์ allOf ตัวอย่างต่อไปนี้จะใส่คำอธิบายประกอบเมธอด setWallpaper() เพื่อระบุว่าผู้เรียกใช้เมธอดต้องมีสิทธิ์ permission.SET_WALLPAPERS

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
@Throws(IOException::class)
abstract fun setWallpaper(bitmap: Bitmap)

ตัวอย่างต่อไปนี้กำหนดให้ผู้เรียกใช้เมธอด copyImageFile() ต้องมีทั้งสิทธิ์อ่านในที่จัดเก็บข้อมูลภายนอกและสิทธิ์อ่านข้อมูลเมตาตำแหน่งในรูปภาพที่คัดลอกมา

@RequiresPermission(
    allOf = [
        Manifest.permission.READ_EXTERNAL_STORAGE,
        Manifest.permission.ACCESS_MEDIA_LOCATION
    ]
)
fun copyImageFile(dest: String, source: String) {
    // ...
}

สำหรับสิทธิ์ใน Intent ให้วางข้อกำหนดสิทธิ์ในช่องสตริงที่กำหนดชื่อการดำเนินการของ Intent ดังนี้

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

สำหรับสิทธิ์ใน Content Provider ที่ต้องใช้สิทธิ์แยกต่างหากสำหรับการเข้าถึงแบบอ่านและเขียน ให้รวมข้อกำหนดสิทธิ์แต่ละรายการไว้ในคำอธิบายประกอบ @RequiresPermission.Read หรือ @RequiresPermission.Write ดังนี้

@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS))
val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")

สิทธิ์โดยอ้อม

เมื่อสิทธิ์ขึ้นอยู่กับค่าที่เฉพาะเจาะจงซึ่งระบุไว้ในพารามิเตอร์ของเมธอด ให้ใช้ @RequiresPermission ในพารามิเตอร์เองโดยไม่ต้องระบุสิทธิ์ที่เฉพาะเจาะจง เช่น เมธอด startActivity(Intent) ใช้สิทธิ์ทางอ้อมใน Intent ที่ส่งไปยังเมธอด ดังนี้

abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)

เมื่อคุณใช้สิทธิ์ทางอ้อม เครื่องมือสร้างจะทำการวิเคราะห์โฟลว์ข้อมูลเพื่อตรวจสอบว่าอาร์กิวเมนต์ที่ส่งไปยังเมธอดมีคำอธิบายประกอบ @RequiresPermission หรือไม่ จากนั้นจึงบังคับใช้คำอธิบายประกอบที่มีอยู่จากพารามิเตอร์ในเมธอดเอง ในตัวอย่าง startActivity(Intent) คำอธิบายประกอบในคลาส Intent จะทำให้เกิดคำเตือนที่ได้จากการใช้ startActivity(Intent) ที่ไม่ถูกต้องเมื่อมีการส่ง Intent ที่ไม่มีสิทธิ์ที่เหมาะสมไปยังเมธอด ดังที่แสดงในรูปที่ 1

รูปที่ 1 คำเตือนที่สร้างขึ้นจากคำอธิบายประกอบสิทธิ์ทางอ้อมในเมธอด startActivity(Intent)

เครื่องมือสร้างจะสร้างคำเตือนใน startActivity(Intent) จากคำอธิบายประกอบในชื่อการดำเนินการตาม Intent ที่เกี่ยวข้องในคลาส Intent ดังนี้

@RequiresPermission(Manifest.permission.CALL_PHONE)
const val ACTION_CALL = "android.intent.action.CALL"

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

คำอธิบายประกอบค่าที่แสดงผล

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

ตัวอย่างเช่น นักพัฒนาซอฟต์แวร์ Java มือใหม่มักเข้าใจผิดว่า <String>.trim() จะนำช่องว่างออกจากสตริงเดิม การใส่คำอธิบายประกอบเมธอดด้วย @CheckResult จะแจ้งการใช้ <String>.trim() ที่ผู้เรียกไม่ได้ดำเนินการใดๆ กับค่าที่แสดงผลของเมธอด

ตัวอย่างต่อไปนี้จะใส่คำอธิบายประกอบเมธอด checkPermissions() เพื่อตรวจสอบว่ามีการอ้างอิงค่าที่แสดงผลของเมธอดจริงหรือไม่ นอกจากนี้ยังระบุชื่อเมธอด enforcePermission() เป็นเมธอดที่จะแนะนำให้นักพัฒนาแอปใช้แทนด้วย

@CheckResult(suggest = "#enforcePermission(String,int,int,String)")
abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int

คำอธิบายประกอบ CallSuper

ใช้คำอธิบายประกอบ @CallSuper เพื่อตรวจสอบว่าเมธอดที่ลบล้างมีการเรียกใช้เมธอดระดับสูงของการใช้งานเมธอด

ตัวอย่างต่อไปนี้จะใส่คำอธิบายประกอบเมธอด onCreate() เพื่อให้แน่ใจว่าการติดตั้งใช้งานเมธอดที่ลบล้างจะเรียกใช้ super.onCreate()

@CallSuper
override fun onCreate(savedInstanceState: Bundle?) {
}

คำอธิบายประกอบ Typedef

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

ใช้คำอธิบายประกอบ @IntDef และ @StringDef เพื่อสร้างคำอธิบายประกอบแบบแจกแจงของชุดจำนวนเต็มและสตริงเพื่อตรวจสอบการอ้างอิงโค้ดประเภทอื่นๆ

คำอธิบายประกอบ Typedef ใช้ @interface เพื่อประกาศประเภทคำอธิบายประกอบที่แจกแจงใหม่ คำอธิบายประกอบ @IntDef และ @StringDef พร้อมกับ @Retention จะใส่คำอธิบายประกอบใหม่และจำเป็นสำหรับการกำหนดประเภทที่แจกแจง คำอธิบายประกอบ @Retention(RetentionPolicy.SOURCE) จะบอกคอมไพเลอร์ไม่ให้จัดเก็บข้อมูลคำอธิบายประกอบที่แจกแจงไว้ในไฟล์ .class

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

// import androidx.annotation.IntDef
// ...
// Define the list of accepted constants and declare the NavigationMode annotation.
@Retention(AnnotationRetention.SOURCE)
@IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS)
annotation class NavigationMode

// Declare the constants.
const val NAVIGATION_MODE_STANDARD = 0
const val NAVIGATION_MODE_LIST = 1
const val NAVIGATION_MODE_TABS = 2

abstract class ActionBar {

    // Decorate the target methods with the annotation.
    // Attach the annotation.
    @get:NavigationMode
    @setparam:NavigationMode
    abstract var navigationMode: Int
}

เมื่อคุณสร้างโค้ดนี้ ระบบจะสร้างคำเตือนหากพารามิเตอร์ mode ไม่อ้างอิงค่าคงที่ที่กำหนดไว้ (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST หรือ NAVIGATION_MODE_TABS)

รวม @IntDef และ @IntRange เพื่อระบุว่าจำนวนเต็มอาจเป็นชุดค่าคงที่ที่กำหนดหรือค่าภายในช่วงก็ได้

เปิดใช้การรวมค่าคงที่กับแฟล็ก

หากผู้ใช้สามารถรวมค่าคงที่ที่อนุญาตเข้ากับแฟล็ก (เช่น |, &, ^ และอื่นๆ) คุณสามารถกำหนดคำอธิบายประกอบด้วยแอตทริบิวต์ flag เพื่อตรวจสอบว่าพารามิเตอร์หรือค่าที่แสดงผลอ้างอิงรูปแบบที่ถูกต้องหรือไม่

ตัวอย่างต่อไปนี้สร้างคำอธิบายประกอบ DisplayOptions ที่มีรายการค่าคงที่ DISPLAY_ ที่ถูกต้อง

// import androidx.annotation.IntDef
// ...

@IntDef(
    flag = true,
    value = [
        DISPLAY_USE_LOGO,
        DISPLAY_SHOW_HOME,
        DISPLAY_HOME_AS_UP,
        DISPLAY_SHOW_TITLE,
        DISPLAY_SHOW_CUSTOM
    ]
)
@Retention(AnnotationRetention.SOURCE)
annotation class DisplayOptions
// ...

เมื่อคุณสร้างโค้ดที่มีแฟล็กคำอธิบายประกอบ ระบบจะสร้างคำเตือนหากพารามิเตอร์ที่ตกแต่งหรือค่าที่แสดงผลไม่ได้อ้างอิงรูปแบบที่ถูกต้อง

เก็บคำอธิบายประกอบไว้

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

ข้อควรระวัง: คลาสและเมธอดที่คุณใส่คำอธิบายประกอบโดยใช้ @Keep จะปรากฏใน APK ของแอปเสมอ แม้ว่าคุณจะไม่เคยอ้างอิงคลาสและเมธอดเหล่านี้ภายในตรรกะของแอปก็ตาม

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

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

คำอธิบายประกอบระดับการเข้าถึงโค้ด

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

แสดงโค้ดสำหรับการทดสอบ

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

ในตัวอย่างต่อไปนี้ โดยปกติแล้ว myMethod() จะเป็น private แต่จะเป็น package-private สำหรับการทดสอบ เมื่อมีการกำหนด VisibleForTesting.PRIVATE Lint จะแสดงข้อความหากมีการเรียกใช้เมธอดนี้จากภายนอกบริบทที่ได้รับอนุญาตโดยการเข้าถึง private เช่น จากหน่วยการคอมไพล์อื่น

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
fun myMethod() {
    // ...
}

นอกจากนี้ คุณยังระบุ @VisibleForTesting(otherwise = VisibleForTesting.NONE) เพื่อระบุว่ามีเมธอดสำหรับการทดสอบเท่านั้นได้ด้วย รูปแบบนี้เหมือนกับการใช้ @RestrictTo(TESTS) ทั้ง 2 วิธีจะทำการตรวจสอบ Lint เหมือนกัน

จำกัด API

คำอธิบายประกอบ @RestrictTo บ่งชี้ว่าการเข้าถึง API ที่มีคำอธิบายประกอบ (แพ็กเกจ คลาส หรือเมธอด) ถูกจำกัด ดังนี้

คลาสย่อย

ใช้รูปแบบคำอธิบายประกอบ @RestrictTo(RestrictTo.Scope.SUBCLASSES) เพื่อจำกัดการเข้าถึง API เฉพาะคลาสย่อยเท่านั้น

เฉพาะคลาสที่ขยายคลาสที่มีคำอธิบายประกอบเท่านั้นที่เข้าถึง API นี้ได้ ตัวแก้ไข protected ของ Java ไม่มีการจำกัดที่เพียงพอ เนื่องจากอนุญาตให้เข้าถึงจากคลาสที่ไม่เกี่ยวข้องภายในแพ็กเกจเดียวกัน นอกจากนี้ ยังมีบางกรณีที่คุณต้องการปล่อย เมธอด public ไว้เพื่อความยืดหยุ่นในอนาคต เนื่องจากคุณไม่สามารถทำให้เมธอด ที่เคยเป็น protected และถูกลบล้างไปแล้วกลับมาเป็น public ได้ แต่คุณต้องการบอก ใบ้ว่าคลาสนั้นมีไว้เพื่อใช้งานภายในคลาสหรือจากคลาสย่อยเท่านั้น

ห้องสมุด

ใช้แบบฟอร์มคำอธิบายประกอบ @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) เพื่อจำกัดการเข้าถึง API ให้เฉพาะไลบรารีของคุณเท่านั้น

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

การทดสอบ

ใช้แบบฟอร์มคำอธิบายประกอบ @RestrictTo(RestrictTo.Scope.TESTS) เพื่อป้องกันไม่ให้นักพัฒนาแอปรายอื่นเข้าถึง API การทดสอบของคุณ

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