DEV Community

Try to avoid comments (most of the time)

Davor Tvorić on May 31, 2021

Writing down a comment when you're coding might seem like you're going to help yourself or someone that might stumble upon your code, but, in reali...
Collapse
 
ashishk1331 profile image
Ashish Khare😎

Commenting on our own code is a part of planning, also it gives you a moment to rethink about your code and its necessity. Things become obsolete because they were written at a specific point of time in the past. Natural fact! Do not cry on that. Try to understand the difference between what is given and what you want. Then act accordingly. Avoiding things is not a solution to everything. Sit down, talk, think and act normal is the solution. Plus, this post seems to me a kickback of your frustration over something obsolete and wrong according to your present. It happens, but don't stop commenting. Everyone knows why the maker made comments. Follow the conventions while break the rules!

Collapse
 
shockwavee profile image
Davor Tvorić

This article is more about writing inline comments inside of your code, not in a general sense of getting feedback on your code. I'm a 100% all for feedback on your code and getting better!
If I have misunderstood you, could you please clarify what you're saying?

Collapse
 
ashishk1331 profile image
Ashish Khare😎

I could have but I myself don't know what I say.

Collapse
 
jhelberg profile image
Joost Helberg

The only comment allowed is "TODO this code may not work for ...".
For the rest, write design and coding documentation and derive your code from that. Literate programming is one way, notebooks (these python things) is another.

Collapse
 
nevcos profile image
Filipe Costa

I love this phrase from Uncle Bob:

A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.

Collapse
 
shockwavee profile image
Davor Tvorić

That one caught my eye, too, it's pretty much what I tried to say :D

Collapse
 
oadrian2 profile image
oadrian2

A variation on your complicated feature would be specification requirements since those tend to be longer-lasting and something the code is working towards.

Collapse
 
shockwavee profile image
Davor Tvorić

Would you say that's a good thing to have in your code or not?

Collapse
 
sharase12 profile image
sharase12 • Edited

This post focuses more on writing inline comments within your code than on receiving feedback on your work in general. I wholeheartedly support obtaining feedback on your code and improving!
quordle

Collapse
 
baukereg profile image
Bauke Regnerus

Another benefit of breaking up logic in small functions is to make it easier to write tests.

Collapse
 
shockwavee profile image
Davor Tvorić

Agreed, definitely!

Collapse
 
drsimplegraffiti profile image
Abayomi Ogunnusi

The take-home is : comments are good but over using it is bad... just like other coding principles like DRY. Thanks for the post....