Sometimes I see devs say things like "good code doesn't need comments". The rationale being, if your code is well-written, it should be self-explan...
For further actions, you may consider blocking this person and/or reporting abuse
in my experience the shorter the code the harder it is to understand because as you said developers are problem solvers so when you find a unique way to solve an issue most of the time the solution would be short and fast especially when you solve an algorithm for example if i said write a code that sums numbers from 1 -> 1m most developers may write a loop but this problem can be solved with just one line with this equation
and if i see something like this without a comment i would freak out.
Sometime fastest code wear strange habits. In such case i prefer writing 50 lines of comment, than rewriting the optimal code.
This is interesting, could you give some examples in rough code?
Like fx. where would you suggest adding comments, maybe some specific instances where you remember a comment saved the day etc.
I'm a huge fan of verbose code, but i've been debugging for almost 14 years now. So i hardly spend much time figuring out how things work unless i am dealing with something entirely new.
So to be frank, i have a huge bias/blindspot.
So examples would help me a lot. :)
I haven't thought of a good example yet. The one in draft right now involves a method that generates a hash token by taking some data and manipulating it a specific way based on how the app does it, and then at some point the dev changed it which causes all my requests to fail.
Without comments, I couldn't remember why it was doing all if those things or how I even figured it out, so I had to go back and understand the app all over again. If I had simply wrote down where to find the algorithm, it would've saved me a lot of time.
But I don't know how relatable this example is.
A bit, I’ve had to add unit tests to enforce not changing certain Functions return values before.
Not all environments are unit test viable, I could see my self adding warning comments if that was the case. :)
That being said, changing the return type of something Is generally very bad, so my hope is that it would be caught in code review first.
Most of the tools I have rely on third party services/data formats, some of which are not designed with the end-user in mind (eg: proprietary formats, internal API's, etc) so I think the issues I'm running into are mostly because I'm doing things people shouldn't be doing lol
A well written unit test explains the contract of the code, what is it supposed to be doing.
And I am in the camp that comments are the exception instead of the rule. I do make a distinction between API documentation/architecture documentation and comments that explain what you are actually doing in the code.
I did expect to see examples in this blog so there was something concrete to agree or disagree with.
Thanks for the feedback. I think unit tests can definitely provide a lot of clues, especially with all of the possible inputs good (and maybe bad) inputs.
High-level documentation I agree should be distinguished from comments, though I believe some tools use class and method comments and such to generate API docs, so it would accomplish two things at once. Plus if I'm reading through the code, it would be easier to just see the comments right there instead of going elsewhere to reference the design docs.
Example is a good idea. I will think of something appropriate to illustrate the purpose of a comment and how it might be useful.
My opinion on this boils down to the fact that I have never been upset to see comments.
For myself I use a module explanation (by file or folder).
It include Nature and origin of data
The goal of the process or features of this module
Restrictions (valid data ranges and type) and pitfalls,
I don't use Var, less possible, No Lamba, or the minimum possible.
and i don't use no meaning locals like simple letter except for a basic iterations.
I Rarely stall on my code like before trying to understand what i did last year for example...
Thanks for the feedback. I like module-level comments as well, so if I see a folder with 10 files, I can go through each of them and quickly look at what purpose they might serve.
There are definitely a lot of language-specific syntaxes. Things that are considered "pythonic" for example might be quite unintuitive for someone that doesn't have a strong grasp of python, and they're spending more time trying to figure out what the code is doing.
If it's for performance reasons, comments are a good compromise because while I might not be able to understand how it works immediately, I can at least know why it's there and that it seems to do what it's supposed to do.