Шуғли шумо чӣ қадар вақт ба шарҳҳо ва ҳуҷҷатгузорӣ ба кодатон илова мекунед?

Шарҳҳо ва ҳуҷҷатгузории код бояд мунтазам илова карда шаванд, махсусан дар ҳолатҳои зерин:

• Ҳангоми навиштани мантиқии мураккаб, ки дар он рафтор аён нест.
• Барои тавсифи API-ҳои умумӣ, усулҳо ва синфҳо.
• Ҳангоми истифодаи қарорҳои ғайриоддӣ ё роҳҳои ивазкунӣ.

Барои таҳияи Android, аксар вақт JavaDoc ё KDoc барои тавсифи функсияҳо ва синфҳо истифода мешаванд. Ин ба дигар таҳиягарон кӯмак мекунад, ки мақсади коди зуд фаҳманд ва нигоҳдорӣ осон шавад.

Маслиҳат барои KDoc барои функсия дар Kotlin:

/**
 * Лод кардани маълумоти корбар бо ID.
 * @param userId идентификатори корбар
 * @return объекти User бо маълумот
 */
fun loadUser(userId: String): User {
    // иҷроиш
}

Муҳим аст, ки шарҳҳои зиёдатӣ, ки танҳо кодро такрор мекунанд, навиштан накунед, балки ба шарҳ додани сабабҳо ва контекст диққат диҳед.