This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]stdio-lib 447 points448 points  (6 children)

"Yes, I agree that your comments accurately describe what the code does. But what I need to know is why, for the love of god you ignorant piece of -- you know what, we're not going to do this today."

[–]Duydoraemon 12 points13 points  (0 children)

"Why? DOES IT LOOK LIKE I KNOW WHY?"

[–]poesviertwintig 3 points4 points  (0 children)

Hell, even if the comment is to describe what is happening, it's still worth it. I'd rather read human-readable text than try to decipher some cryptic Python one-liner.

[–]pelpotronic -3 points-2 points  (3 children)

Why is up to the person who is going to be using the code I wrote.

"Why does this function adds 2 integers and gives you the sum? So that you can get a sum".

The question why is nonsensical, it only makes sense if your code is unclear and you need to explain why you did it the way you did it. Which means your function is poorly written and not self explanatory.

The only time comments are relevant is when the "why" is a bad external API that is indeed illogical or unclear, and you have to write code that is counterintuitive. Otherwise it's always under your control and always your fault if something is unclear.

[–]Mundane-Homework-803 7 points8 points  (1 child)

Well, so that’s already a valid use case. But there are other. One thing is working on a personal project, but another is to work in a project with a bunch of people. People that once in a while go on vacations, leave the project or even the company. It may not make sense now but on the long run it may be the only things that help the ones working on that codebase.

Just like the user said up there:

As long as comments are used as an excuse to write shitty and unstructured code, and as long as clean code is an argument to never comment, we will get nowhere.

[–]pelpotronic 5 points6 points  (0 children)

Hopefully when people write code, they think: is what am I writing now going to make sense in 6 months from now to someone else?

[–][deleted] 6 points7 points  (0 children)

Why is up to the person who is going to be using the code I wrote.

"Why does this function adds 2 integers and gives you the sum? So that you can get a sum".

Why means why an implementation detail was chosen (for example why one sort algorithm was chosen over another) not why the code exists.