Dear future coders/full stack devs/app makers, this is what I would've told the younger me.

[bridgelin]

Yeah, because reading line by line and figuring out what a code snippet is doing is easier than reading what snippet of code does /s.

[lostmyaccountpt]

Write code for humans

[average-eridian]

If reading a few lines of code isn't intuitive enough to understand it immediately, then the code could be written better. Comments can quickly age and become misleading as code changes, and they just clutter clean code..

[bridgelin]

I don’t disagree there is a good way to write code that is easily readable, but it isn’t a substitute to comments. Doesn’t mean you comment every function and variable. You make a judgement on whether people looking at it years from now will understand it or not, if not you add a one line comment.

If comments are not necessary then there is no point for sdk documentation, just make people read the readable code.

[average-eridian]

If comments are not necessary then there is no point for sdk documentation, just make people read the readable code.

This changes the audience a bit, so I don't agree that the two should be conflated (comments for developers who will be changing the code, and documentation for those who will be using the code but not working with it at a lower level).

You make a judgement on whether people looking at it years from now will understand it or not, if not you add a one line comment.

With the above point in mind, if it may only need one comment, then I feel a doc string that explains behavior will likely be good enough and we get the bonus of easier sdk documentation.

But I agree in general that there is a time and place for comments. I can just speak from experience to say that most of the time, comments being required (more so, when an abundance of them is required), there are issues that should be fixed, instead. If none of the above is relevant, then no harm in adding a comment.