Under review


Blu 2 months ago updated by Alexander Shvets 2 months ago 1

My coworker linked me here to show that code comments are unnecessary. While I agree in general, this was argument against using doxygen - and those, in my opinion, are essential for any project that has many contributors; doxygen-styled comments are not comments about the code flow, but rather a convenient form of documentation that's essential for any project that has more than a handful of contributors. It's not meant to explain the code, but rather to give a tl;dr version for it's consumer.
What do you think? Especially in context of loosely-typed languages, where it can/should have more information than actual fn definition.

Under review


Thanks for the good question! Frankly, I don't see a big difference. I would ask myself whether the added bloat really adds anything valuable, be that regular comments or Doxygen.

If you use Doxygen for marking out typing info in a language that lacks it (earlier versions of PHP, for example) then this is probably okay. If you mark types that are already obvious, then it's just bloat. I have seen projects where the Doxygen documentation became an obsessive thing, where people were adding Doxygen comments to everything, important or not, just for the sake of consistency.