undefined

points

by awesome_dude1 days ago |

comments

by AdieuToLogic1 days ago|

[-]

> Yes comments can lie ...

Comments only lie if they are allowed to become one.

Just like a method name can lie. Or a class name. Or ...

by bonesss1 days ago|

parent|

[-]

Right.

The compiler ensures that the code is valid, and what ensures that ‘// used a suboptimal sort because reasons’ is updated during a global refactor that changes the method? … some dude living in that module all day every day exercising monk-like discipline? That is unwanted for a few reasons, notably the routine failures of such efforts over time.

Module names and namespaces and function names can lie. But they are also corrected wholesale and en-masse when first fixed, those lies are made apparent when using them. If right_pad() is updated so it’s actually left_pad() it gets caught as an error source during implementation or as an independent naming issue in working code. If that misrepresentation is the source of an emergent error it will be visible and unavoidable in debugging if it’s in code, and the subsequent correction will be validated by the compiler (and therefore amenable to automated testing).

Lies in comments don’t reduce the potential for lies in code, but keeping inline comments minimal and focused on exceptional circumstances can meaningfully reduce the number of aggregate lies in a codebase.

by deathanatos1 days ago|

parent|

[-]

> what ensures that ‘// used a suboptimal sort because reasons’ is updated during a global refactor that changes the method?

And for that matter, what ensures it is even correct the first time it is written?

(I think this is probably the far more common problem when I'm looking at a bug, newly discovered: the logic was broken on day 1, hasn't changed since; the comment, when there is one, is as wrong as the day it was written.)

by awesome_dude1 days ago|

parent|

[-]

But, you've still got an idea of why things were done the way they were - radio silence is....

Go ask Steve, he wrote it, oh, he left about 3 years ago... does anyone know what he was thinking?

by larusso1 days ago|

prev|

[-]

I don’t disagree here. I personally like to put the why into commit messages though. It’s my longtime fight to make people write better commit messages. Most devs I see describe what they did. And in most cases that is visible from the change-set. One has to be careful here as similar to line documentation etc everything changes with size. But I prefer if the why isn’t sprinkled between source. But I’m not dogmatic about it. It really depends.

by awesome_dude1 days ago|

parent|

[-]

https://conventionalcommits.org/en/v1.0.0/

I <3 great (edit: improve clarity) commit comments, but I am leaning more heavily to good comments at the same level as the dev is reading - right there in the code - rather than telling them to look at git blame, find the appropriate commit message (keeping in mind that there might have been changes to the line(s) of code and commits might intertwine, thus making it a mission to find the commit holding the right message(s).

edit: I forgot to add - commit messages are great, assuming the people merging the PR into main aren't squashing the commits (a lot of people do this because of a lack of understanding of our friend rebase)

by palata1 days ago|

prev|

[-]

IMHO, you shouldn't have to justify yourself ("yeah yeah, this is not optimal, I know it because I am not an idiot"). Just write your code in O(n) if that's good enough now. Later, a developer may see that it needs to be optimised, and they should assume that the previous developer was not an idiot and that it was fine with O(n), but now it's not anymore.

Or do you think that your example comment brings knowledge other than "I want you to know that I know that it is not optimal, but it is fine, so don't judge me"?

by awesome_dude22 hours ago|

parent|

[-]

A little bit of "Don't judge me" and a little bit of "I nearly fell into a trap here, and started writing O(log n) search, but realised that it was a waste of time and effort (and would actually slow things down) - so to save you from that trap here's a note"

by palata19 hours ago|

parent|

[-]

The risk with that is that because it was not obvious to you does not necessarily mean it's not obvious to others.

Over the years, I have seen many, many juniors wrapping simple CLI invocations in a script because they just learned about them and thought they weren't obvious.

- clone_git_repo.sh

- run_docker_container.sh

I do agree that something actually tricky should be commented. But that's exceedingly rare.

by awesome_dude15 hours ago|

parent|

[-]

I mean, the whole point of explicit being superior to implicit is because what's obvious to some isn't necessarily obvious to everyone.

Someone following me could look at it and go.. "well duh" and that's not going to hurt anyone, but if I didn't put that comment and someone refractometer, then we have someone redoing and then undoing, for no good reason.

There's that meme where people are told to update the number of hours wasted because people try to refactor some coffee and have to undo it because it doesn't work

by palata5 hours ago|

parent|

[-]

Do you write a comment before every for loop to explain how a for loop works? Do you write a comment above that to remind the reader that the next few lines are written in, say, Go, just like in the rest of the file? Do you write a comment explaining that the text appearing on the screen is actually digital and will disappear when you turn off the computer?

Obviously you don't, because you assume that the person reading that code has some level of knowledge. You don't say "well, it may not be obvious to everybody, so I need to explain everything".

I guess where we differ is that to me, a professional software developer should be able to understand good code. If they aren't, they are a junior who needs practice. But I am for designing tools for the professionals, not for the apprentices. The goal of an apprentice is to become a professional, not to remain an apprentice forever.