Why Developers Write Weird Code Comments (And What They Reveal)

Introduction

Developers consider code an asset and the most valuable element of a software project, deserving time, effort, and money. Yet the motivations behind writing comments—especially non‑standard or humorous ones—are often unclear. This article investigates those motivations and showcases interesting examples.

A Brief History

Just as cave paintings recorded human experiences, early programmers left remarks on punch cards and early computers. The first programs contained sparse, sometimes whimsical comments, reflecting the human desire to communicate with future readers.

Comment Statistics

Analyzing several codebases yields the following approximate comment ratios:

C++: 1,082,000 lines, 15% comments

C#: 509,000 lines, 6% comments

Java: 80,000 lines, 16% comments

These figures invite speculation about developers' attitudes toward commenting.

Notable Comment Examples

Below are selected excerpts from real-world code, illustrating various styles:

// Dear future me. Please forgive me.
// I can't even begin to express how sorry I am.

/**
 * For the brave souls who get this far: You are the chosen ones,
 * the valiant knights of programming who toil away, without rest,
 * fixing our most awful code. To you, true saviors, kings of men,
 * I say this: never gonna give you up, never gonna let you down,
 * never gonna run around and desert you. Never gonna make you cry,
 * never gonna say goodbye. Never gonna tell a lie and hurt you.
 */

// Dear maintainer:
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// total_hours_wasted_here = 42

// Magic. Do not touch.

// If this comment is removed the program will blow up

// I know the line below is wrong, but it came that way from our IP
// vendor, and the driver won't work if you "fix" it. I've had to
// revert this change 4 times now. Leave it alone, or
// I will hunt you down and hurt you

These snippets demonstrate humor, self‑deprecation, warnings, and even cryptic messages that convey personality and emotion.

Types of Comments

Comments can be categorized as:

Poetic or lyrical : code poems or song lyrics.

Interactive : counters or jokes that engage future readers.

Magical : mystifying remarks about code that only the author understands.

Warning or prohibitive : directives not to modify code.

Self‑explanatory : straightforward explanations of intent.

Even absurd or offensive comments appear, reflecting developers' moods, deadlines, or workplace culture.

Conclusion

Code comments are more than documentation; they are a form of communication, humor, and personal expression. While excessive or obscure remarks can hinder readability, well‑placed, thoughtful comments foster collaboration and preserve knowledge. Developers are encouraged to comment responsibly, balancing clarity with personality.