Code Communication Q&A

[00:00:00]
>> Speaker 1: Curious what the role of something like JSDoc or other notation standards are. It kinda sounds like there's the issue of writing code for the machine and then writing code for the humans who have to read it weeks down the road. And I'm very persuaded by the arguments about using explicit coercion, but are there other cases where you have encountered or would recommend ancillary tactics like that?

[00:00:30]
>> Kyle Simpson: Well, I certainly think if you think about coding on the whole, it's a great question, by the way. If you think about coding on the whole as a way to communicate my ideas, then there are lots of ways to communicate ideas. One of the ways is in the code that you write, one of the ways is in the ancillary stuff that you mentioned, like for example code comments.

[00:00:50]
Now some people tell you, nah you should never need code comments, code should explain itself. You should not have more reliance upon code comments than the code. And I've seen code bases that are like that, that are so inscrutable that without the code comment, nobody's figuring it out.

[00:01:09]
But code comments are not a bad thing to be avoided. They're not exposing some weakness of the program. Here's the problem with code comments. People write the what in their code comment, I'm sorry, they write the how in their code comment. Like you have a line that says, i++, and then you say something like increment i is the code comment.

[00:01:32]
I know it's incrementing i, I can see that. Here's what I want the code comment to tell me, why. Why do you need to increment, and why only by 1, why not by 2 or 12? Tell me why, and sometimes maybe tell me how. But don't tell me what, that's what the code's for.

[00:01:47]
So yes, you can communicate well with your code. If you did a JS doc on this function and said, these two parameters receive either strings or numbers, then you're very clearly signaling to everybody, be aware that some coercion may happen. But it's only between strings and numbers, and so we know we have narrowed down the scope of corner cases that we need to be concerned about.

[00:02:07]
Absolutely, code comments can be useful, I wouldn't rely entirely on them. I think there's lots of things we can do in our code to be obvious.