DEV Community

loading...

Discussion on: //TODO: Write a better comment

Collapse
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 blog.codinghorror.com/code-tells-y... 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.

Collapse
adammc331 profile image
Adam McNeilly Author

Ahh it was definitely coding horror! Thanks!