Simplicity is the ultimate sophistication. — Leonardo da Vinci
You’re staring at a wall of code resembling a Gordian knot of Klingon. What’s making it worse? A sea of code comments so long that you’d need a bathroom break just to read them all! Let’s fix that.
Adopt the mindset of someone unfamiliar with the project to ensure simplicity. One approach is to separate the process of writing your comments from reviewing them; proofreading your comments without code context in mind helps ensure they are clear and concise for future readers.
Use self-contained comments to clearly convey intent without relying on the surrounding code for context. If you need to read the code to understand the comment, you’ve got it backwards!
Not self-contained; requires reading the code
Suggested alternative
// Respond to flashing lights in // rearview mirror.
// Pull over for police and/or yield to
// emergency vehicles.
while flashing_lights_in_rearview_mirror() {
if !move_to_slower_lane() { stop_on_shoulder(); }
}
Include only essential information in the comments and leverage external references to reduce cognitive load on the reader. For comments suggesting improvements, links to relevant bugs or docs keep comments concise while providing a path for follow-up. Note that linked docs may be inaccessible, so use judgment in deciding how much context to include directly in the comments.
Too much potential improvement in the comment
// The local bus offers good average- // case performance. Consider using // the subway which may be faster
// depending on factors like time of // day, weather, etc.
// TODO: Consider various factors to // present the best transit option.
// See issuetracker.fake/bus-vs-subway
commute_by_local_bus();
Avoid extensive implementation details in function-level comments. When implementations change, such details often result in outdated comments. Instead, describe the public API contract, focusing on what the function does.
Too much implementation detail
// For high-traffic intersections // prone to accidents, pass through // the intersection and make 3 right // turns, which is equivalent to // turning left.
// Perform a safe left turn at a
// high-traffic intersection.
// See discussion in
// dangerous-left-turns.fake/about.
fn safe_turn_left() {
go_straight();
for i in 0..3 {
turn_right();
