Crafting Code That Speaks for Itself: A Programmer‘s Guide to Comments

As an experienced developer, I often mentor new programmers. And there‘s one question I get asked constantly:

"How much should I comment my code?"

It‘s a fair question. Comments are the translator that allows your code to speak eloquently to other developers. But over-commenting creates clutter. Under-commenting leaves others baffled.

So how do you strike that delicate balance?

In this guide, we‘ll cover everything you need to know about comments – and I‘ll use examples in 15 languages to show you best practices.

Why Comments Matter

Early on, I wasn‘t the best commenter. I assumed my code was self-explanatory. One day, I was asked to update a tricky section that a former co-worker had written. And boy was I thankful for their judicious comments sprinkled throughout!

Comments don‘t just help others understand your code. They help future you decipher your own logic months later.

Beyond maintaining comprehension, well-written comments also:

  • Strengthen collaboration – Teams can coordinate better.
  • Expedite on-boarding – New hires get productive faster.
  • Speed up troubleshooting – Pinpoint bugs rapidly.

In my experience, good commenting practices directly correlate with engineering teams that build higher quality software faster.

But don‘t just take my word for it. As this survey shows, over 90% of developers believe well-documented code boasts better readability, reusability and maintainability:

Survey results

Now that you know why commenting matters, let‘s explore how to write effective comments across 15 diverse programming languages.

Overview of Comment Syntax

Here‘s a quick reference guide before we dive in:

Language Single-Line Multi-line
C/C++ // / /
Python # """ """
Java // / /
JavaScript // / /
PHP // / /
C# // / /
Ruby # =begin =end
*See all 15 languages…*
Language Single-Line Multi-line
Visual Basic ‘‘‘ ‘‘‘
R # Doesn‘t support multi-line
Objective C // / /
Swift // / /
Perl # =pod =cut
Scala // / /
Go // / /
Kotlin // / /

Now let‘s explore proper comment practices with examples in each language.

Effective Commenting in C/C++

As one of the first languages I learned, C/C++ holds a special place in my heart. It‘s still widely-used today, powering major operating systems like Windows and Linux.

Let‘s look at examples of single and multi-line comments:

// Calculate distance travelled  
int distance = speed * time;

/*
Multi-line comments should be used to:
1. Explain complex algorithms  
2. Provide usage info for functions
3. Organize sections of code
*/

Learnings from 20+ Years of C/C++

Over two decades of C/C++, I‘ve arrived at these guidelines:

Do use single-line comments for quick notes on individual lines

Avoid end-of-line single comments explaining the obvious

Consider multi-line comments before complex sections or functions

Adding too many one-liners clutters the code. Instead, narrate the tricky stuff in dedicated comment blocks before diving in. Like this:

/*
The follow series of 4 functions handles error 
checking. Each builds on previous validations.
*/

functionOne(){
   // Input validation   
}

functionTwo(){
   // Authorization check
} 

This way developers see the big picture first.

Next up – Python!


## Effective Commenting in Python

As Python exploded in popularity for machine learning and data science, I made sure to add it to my coding repertoire. 

Let‘s compare single-line versus multi-line:

```python
# Fetch user profile data
user = fetch_profile(user_id) 

"""  
The load_users function checks permissions
before returning user list data
"""
def load_users():
   # Authorize 
   if (unauthorized) {
     return False
   }

   # Get users
   users = db.query(Users)  
   return users

Here are my Python commenting recommendations after years of experience:

Do use single line comments to document methods and classes

Consider multi-line docstrings for longer usage info

Avoid redundant comments that repeat what the code says

I also highly recommend following PEP-8 style guidelines which introduce consistency for Python comments.

Now onto JavaScript!

Commenting Effectively in JavaScript

In the world of web development, JavaScript skills are in high demand. As JS has gone from powering simple buttons to complex web apps, mastering its comment syntax is vital.

// Get form data
const data = getFormData(); 

/* 
The parseUserFunction handles validating
user-entered data from the Signup form
*/
function parseUserData() {
  // Check types
  if (!isString(data.name)) {
    throw Error("Invalid name");
  }

  // Validate 
  if (!isValidZipcode(data.zip)) {
    throw Error("Zipcode Invalid")
  }
}

My JS commenting best practices may help:

Do comment before complex functions to set context

Consider using JSDoc single-line style for auto-documentation

Avoid redundant comments that hurt readability

Now that you‘ve seen examples in C++, Python and JS, let‘s quickly run through best practices in 12 more languages:

Commenting Best Practices

PHP

// Connect to database
$db = new Db();

/*
This class handles querying and returning
results from MySQL in a PDO-friendly format  
*/
class Db {
  // Database credentials 
  private $username = ‘appuser‘;
}

Do use single-line comments before class methods and properties

Avoid redundant end-of-line comments

C#

// Initialize component
component = new Component();

/*
The Component class handles setting up and 
configuring the user interface‘s core UI element
*/
public class Component {
  // Default configuration
  string color = "blue"; 
}

Do comment before complex classes and methods

Consider using XML doc style formatting

Ruby

# Store user location
location = params[:location]

=begin
The UserProfile class fetches, parses, 
and exposes user profile data
=end
class UserProfile
  # Format date of birth
  dob = date(:db_date) 
end

Do comment before key class definitions

Avoid redundant end-of-line comments

And in 10 more languages I‘ve worked with…

Now you‘ve seen effective comment practices across 15 diverse programming languages.

While syntax details vary, the fundamentals remain constant. Judicious comments improve comprehension, collaboration and maintainability.

So be generous, but also strategic with your comments. Craft code that speaks eloquently for itself!

Your future self will thank you. And so will all other developers who inherit your code.

Have questions? Just comment below! I read and respond to every one.