DEV Community


Discussion on: //TODO: Write a better comment

briwa profile image
briwa • Edited

I cannot remember where I first heard this quote, but it has always resonated with me. The code should tell you what is happening, but the comments can tell you why.

I think it comes from which I wholeheartedly agree.

And you're right, going slightly verbose on comments on public interfaces of your API may only be allowed only if it's for documentation generation purpose. Libraries like Typedoc for Typescript (a little bit OOT here) generate documentations extracted from the comments, as other people may have mentioned.

adammc331 profile image
Adam McNeilly Author

Ahh it was definitely coding horror! Thanks!