• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar
  • Skip to footer
cropped CodeSpecialist e1592127475203

Code Specialist

Code and Programming Blog

  • Home
  • Clean Code
  • Code Principles
  • Code Interview
  • Python

Comments – What you should keep in mind

Comments are one of the first features everybody gets to know when learning a new programming language. They can be useful for describing the functionality of code-segments or giving additional information about some code. There are many good reasons to use comments. However, you should still keep a few things in mind when you write them!

Home » Write Better Code » Comments – What you should keep in mind

July 22, 2020 by Jonas Scholl Leave a Comment

Contents hide
1 Do we really need comments?
2 How to let your code speak for itself
3 Comments lie
4 So it’s not allowed to write comments any more?

Do we really need comments?

Nowadays, everyone uses source code management systems (like GitHub for instance), especially when working with multiple developers on one project. If you don’t use a code management system for your projects, consider migrating your project to use one. Even if you work alone on your project – it’s still very useful.

With source code management systems, you can find every written line in the project. It doesn’t matter if someone deleted it a long time ago, you can always look up every older version. So you don’t need to comment-out code segments any more! Furthermore, when you have commented-out code in your project, it’s very likely for it to remain for a long time. And someday you ask yourself: What is this code and why is it here? Maybe you don’t even dare to delete it, because it could be from someone else and still relevant. In the end, it’s always better to instantly delete unused code.

Okay, to comment-out code isn’t a good idea. But it’s still very useful to describe the code with comments, so other ones can understand it better, right? No, not in most cases.
If you need to explain in every line what your code does, it’s just not readable. There are so many ways to structure and style your code so it becomes more readable. Consider this example, where you only have a chance to understand what’s going on by reading the comments:

This code actually works with semicolon-separated CSV files, but it’s really hard to read. So how can we improve this little mess?

How to let your code speak for itself

There are a few ways to let your code tell what it’s doing. The goal is that the person reading your code can easily understand what’s going on, just by reading the actual code – and not any comments.

  1. Use meaningful names

    Every programmer probably has already heard this advice somewhere. And few programmers will say: “Ah, nothing easier than that! My names are always understandable, it’s no hard deal”. I think most of the people who said that (and I’m including me too) wouldn’t understand some code they have written a few years ago in some old project because it can be really hard to give meaningful names an outsider would understand.

  2. Don’t get too big

    Especially in large and complex projects with thousands of lines of code, there are often situations where functions, classes, etc. get really big. This causes various problems: On the one hand, it’s just hard to read and keep the context in mind when you have to scroll down a few times for reading one function. On the other hand, giving meaningful names is much easier when you separate your code into different parts which you can give describing names.

  3. Abstractions are your friends

    This point goes hand in hand with the previous ones. Try to abstract everything you do. By using abstractions, you have lots of opportunities to give explaining names for the different abstraction levels. Additionally, you prevent your functions, classes, etc. to get too big. The idea of this approach is to hide further details behind every abstraction, and every time you dive deeper, you get to see more detail. Mostly it isn’t necessary to know the details from another point of view, and it’s way easier to understand the code’s purpose from a high-level perspective.

With these concepts in mind, we can refactor the previous code example a bit. After doing that, it looks like this:

This looks much more readable now, right? The code got three times longer than the old version, but now it’s way more readable. There are also a few layers of abstraction: The top-level function doesn’t show much detail. But every time you move an abstraction level deeper, it reveals more information.

Learn more about code principles (Affiliate)

Comments lie

Another problem with comments is that they lie. By saying that, I mean that you can’t really trust what comments say about the code. They always could be outdated and give wrong information about the code.

In the common case, the code we write changes many times and is never “perfect”. As the project you’re working on evolves and the requirements change, the code has to evolve too. Furthermore, nobody can write clean and perfect code instantly. Writing code is always an iterative process where you revise and improve the code in each step.

These continuous changes make it really hard to keep all the comments up to date. Imagine there is a comment in every second line of your code, or even more! On the one hand, it’s really nasty and time-consuming having to change a comment every time you change something in the code. On the other hand, it’s nearly impossible to keep all comments up to date, there will always be an unintentionally outdated one. With modern IDEs, it is very easy to refactor code by allowing the program to do so. Nowadays, changing names or cleaning up unused code are standards for every professional IDE. But in this way, the IDE only refactors the code and not the comments, how could it? It has inadvertently made the comments lying about the code.

So it’s not allowed to write comments any more?

After all these problematic issues about writing comments, we could come to the conclusion that we shouldn’t write comments at all. But I can tell you this is not the case. And you can definitely write really good code with the usage of useful comments. First and foremost, this post wants to draw attention to the various problems when writing comments. We can also write better code that speaks for itself without writing comments.

There are still a few cases where it’s inevitable to use comments. Most projects should have documentation, which often uses comments. Especially when the code or some interfaces to use it are available for externals, good documentation is essential. Either way, it would definitely make sense to explain the code’s functionality when it solves complex problems. Then it’s quite helpful for others to understand what the code does, without needing to understand the complex code. By writing comments like this, they also are less likely to lie about the code after refactoring. But you still have to adjust the comments and the documentation whenever the general behavioral changes.

To sum up, comments can be very helpful in writing understandable code. However, overusing them is never a good choice. They pose some relevant difficulties that everyone needs to be aware of.

Download Source Files
jonas scholl
Jonas Scholl

There is nothing that excites me more than solving problems and understanding complex concepts. I want to share this enthusiasm by making complex things as simple as possible, so everyone can understand them. Nothing is more frustrating than trying to understand a topic with incomprehensible explanations. That’s why I want to inspire you to become a better developer by simplifying concepts and explaining issues clearly.

Book Recommendations on Clean Code (Affiliate)

Category iconWrite Better Code Tag iconClean Code,  Comments,  Readability,  Simple is good

Related Posts

mossy stone
SOLID Principles with Python Code Examples
March 15, 2021
electrical switches
Python Switch-Statement Alternative
October 25, 2020
questionmarks
Use Python Type Hints!
August 17, 2020

Reader Interactions

Leave a Reply Cancel reply

Your email address will not be published.

Primary Sidebar

Search

Categories

  • Algorithms
  • Cloud
  • Code Interview
  • Code Principles
  • Environment
  • Errors
  • Hardware
  • Learn to Code
  • Nice to know
  • Object Orientation
  • Python
  • Technical Background
  • Write Better Code

Tags

Alternative (1) Announcement (1) Clean Code (7) Cloud Foundry (1) Cloud Native (1) Code (1) Code Interview Question (2) Code Philosophy (1) Comments (1) Computer Graphics (2) Concurrency (1) Control Characters (1) Data Science (1) Data Structures (1) decorators (2) dictionaries (3) Easter Eggs (1) funny (1) Github Actions (1) Marching Cubes (1) Meshing (1) Microservice (1) Nice to know (1) Parallelisation (1) Programming Facts (1) Pythonic (3) PyYAML (1) Readability (4) Simple is good (2) Software Engineering (2) switch (1) Syntax (1) Tricks (1) type hints (1) Ubuntu 20.04 (1) Underscores (1) Unix (1) Video (1) Virtualization with Windows (1)

Footer

Recent Posts

  • Cloud Foundry Components
  • No matching distribution found for pkg-resources==0.0.0
  • SOLID Principles with Python Code Examples
  • 5 Hardware Ideas to Upgrade your Programming Experience
  • 5 Programming facts every programmer must know

Tags

Alternative Announcement Clean Code Cloud Foundry Cloud Native Code Code Interview Question Code Philosophy Comments Computer Graphics Concurrency Control Characters Data Science Data Structures decorators dictionaries Easter Eggs funny Github Actions Marching Cubes Meshing Microservice Nice to know Parallelisation Programming Facts Pythonic PyYAML Readability Simple is good Software Engineering switch Syntax Tricks type hints Ubuntu 20.04 Underscores Unix Video Virtualization with Windows

Categories

  • Algorithms
  • Cloud
  • Code Interview
  • Code Principles
  • Environment
  • Errors
  • Hardware
  • Learn to Code
  • Nice to know
  • Object Orientation
  • Python
  • Technical Background
  • Write Better Code

Recent Comments

  • Nina on Bubble Sort in Python and how to Visualize it
  • Bhan on Concurrency in Python

Follow Us

  • Facebook
  • Instagram
  • Pinterest
  • Twitter

Quicklinks

  • About us
  • Become a writer
  • Guest Post

Privacy Policy | Legal Notice | Contact

 

All rights reserved © 2020-2021 code-specialist.com