What is the purpose of a comment? - Robert C. Martin (Uncle Bob)

#cleancode #softwaredevelopment #unclebob #cleanarchitecture #softwaredevelopmenttips #coding #codesmells

In this video Robert C. Martin a.k.a Uncle Bob speaks on the true purpose of a comment. He talks about the problems that come when programmers add comments to code without discernment, and how misleading bad comments can be. What do you think?

[eksortso]

Interesting take. I tend to scatter TODOs in my comments, use them as reminders to myself to address open issues. Once I write code that can describe what it's doing, the comments and TODOs get erased. But I'm loquacious by nature, so I could stand to get by with fewer comments and with more expressive code.

[jgoemat]

Sounds like some people don't have to work with any systems and data created by other people...

[tux.solbakk]

I like to be able to use comments to provide intellisense. Writing good comments on functions and methods, I find is nice so that I get those up when using them without having to look at their source code at all.

[scrimb]

i agree that this is 100% true for code that doesn't need to be explained. there's no need to explain the obvious, though unfortunately in 2024, comments are used not just for explaining confusing code; but also to provide information to transpilers, text editor language servers among other editor extensions that parse your text file

an example of this is annotating javascript variable declarations with JSDoc comments with type hints so the user not only knows what type a variable is supposed to be, but they also get intellisense when referencing the variable. this makes it so that they get instant inline documentation without having to open a manual

it's important to remember that even though our grandfathers are good at what they did, their wisdom will not always be applicable in a rapidly changing ecosystem. regardless, i appreciate their insights

[autokymatic]

I add comments for the reasons code does something, or to create visually different "bookmarks", and I write comments for myself, because I won't always remember why I did something years later, and I write comments for the people who will maintain code after me. As there are no guarantees about how good others will be at their job, and because I care about my employer and/or customers, I don't want them to suffer longer downtimes for pedantic ego-filled arguments against good commenting practices.

[oakley]

I like the Code Aesthetic take on comments, which is basically this, comments are just to explain what the code doesnt say.

[ygstuff]

In a perfect world (world with code written in a perfect manner), comments would not be required.
But I've found that code is written by people, and people are far from perfect, and people change over time (as does their coding skill-level).

My first rule for commenting is, "Comment as though I am going to be reading this code 2 months or 2 years from now...will I understand why I wrote it this way? Can a comment explain the logic/rationale, the purpose of the variables, and why the FOR loop starts at 2 instead of 0 or 1?)

My second rule for commenting is, "Comment as though someone not familiar with the code/system is looking through it to find a specific code block--why make give them a hassle in deciphering code? Just find the comment that encapsulates the requisite operation (open files/connect to database, process records, encrypt data flow, etc...)

My third rule of commenting, "If there are no comments in the code, this automatically increases the proposed time to fix & test any code changes...and time for commenting."

[oliversteffe]

I use comments to mark why I created the function and link it do the storry or. bug.

[icylace]

Including any mandatory copyright notices in your code is a reason to use comments.

[johnidouglasmarangon]

I agree with Uncle Bob. Unit tests can also help developers understand code by avoiding comments.

[teddymasters]

I personally also think of comments as an explanation of why more than an explanation of what

[JehovahsaysNetworth]

@DevToolMadeSimple The existence of the function comments in computer language is because it is a command line help command syntax for example- > c:\help dir List all available commands ( + Description )
<?php # echo 'List all available commands + Description';?>