A code comment is an explanatory annotation embedded in source code and generally ignored during execution. It communicates intent, behavior, constraints, and changes to developers, testers, API users, and future maintainers. section 4.5 section 4.5.1
Useful comments address a specific communication problem without duplicating code:
- Explain behavior that is easy to misuse or difficult to infer, especially in APIs and automated tests. section 4.5.1 section 3.3.3
- Prefer enough detail to guide readers, but avoid unnecessary annotations that increase maintenance work. section 4.5.1
- Use an LLM to draft comments from existing code, while checking that the code remains unchanged and that each comment matches its implementation. section 4.5.1 section 8.2.1
Annotating a timesheet class
A Java Timesheet class stores project durations in a ConcurrentHashMap, normalizes project names to lowercase, and rejects null names or nonpositive durations. Generated comments can clarify these behaviors, such as the map’s key/value roles and the normalization rule. They can also over-explain routine code, so a developer must select and verify the useful annotations. section 4.5.1
###
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
public class Timesheet {
private ConcurrentHashMap<String, Long> timesheets = new
➥ConcurrentHashMap<>();
public boolean submitTimesheet(String projectName, long duration) {
if (projectName != null && duration > 0) {
projectName = projectName.toLowerCase();
timesheets.put(projectName,
➥timesheets.getOrDefault(projectName, 0L) + duration);
return true;
} else {
return false;
}
}
public Collection<Long> getTimesheets() {
return timesheets.values();
}
public long getTotalTimesheetHours(String projectName) {
return timesheets.getOrDefault(projectName.toLowerCase(), 0L);
}
}
###
Inspect the original Timesheet implementation before comparing it with generated comments; this supports checking whether annotation changed the code. section 4.5.1
