Re: Doxygen comments in C++ source
julian.rohrhuber-QYZGCWsIODmAF8UT6DzBU6xOck334EZe@public.gmane.org
| Newsgroups | gmane.comp.audio.supercollider.devel |
|---|---|
| Message-ID | <[email protected]> |
> On 07.02.2018, at 22:21, [email protected] wrote: > > > > On Wed, Feb 7, 2018 at 12:34 PM, <[email protected]> wrote: > > > Also, by following the principle of: "if you find yourself documenting a piece of code within a function, stop, take that code out into a new function whose name is the text of the comment", you will find you often don't need to document functions. They say what they do. > > When the function is a 500+ LOC behemoth with no unit tests and several single-letter-name variables, that's simply not realistic advice. > > Sure it is. It is the way you make a 500 line function become a number of 25 line functions. Yes, it’s very good advice. It is better to spend more time with trying to find the perfect method name, than to think about how to document it. And better to spend more time with refactoring until it is balanced before documenting it. Words are often not a good way to explain code anyhow.
signature.asc
(application/pgp-signature, 833 B)
-----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEE2f9AlUAPrk+1WzZZhbzp9aOW3OYFAlp8gcsACgkQhbzp9aOW 3OZ3EA//ZWcuu9aXU7oW4RHZMxaRj19crLrfFqQ4R7HNrHzqoTy2ckhUYMQZ2hOb 8SewvTOCxsUrTD7+f3xKPIpLMiZMAtKmYpGzOeoW0jaFiXCaQ4xSjMG8fkMrGHPU Le5n4IaCKI3pK89CzbN99UxUJbK0S+yOUBGwJRA3MH5p3pWAxZ+G7QHhXUsk6PS3 G+sw2N8eLpp5AhN7SWlkS2Ye+d+i3R9JP46uLd6IrRQaOvuOhGCd7zb5abyvOnjs jfCX2P8bcSBOqvP0g3l0r4MsMeD3VPy6rBjmuiDjOMSdCitIlLW1vE1+ow6Fntgt kfS08KAC83/k9xTFUa+wZn71WVGlbHOzU0hcidsnlYb2QFHy1RK842s3flqS9Z7F xHPTZsdgCCED5f2jVeV1cMEgr0SBV4+blpvj497Kg2rXwEyYKqG9VFJD5RRKpNTs i4ZmFtug4pCAJGtMEl8oogwa6a9dPs538RmMMMXh8SvKguX90yHBvpt1n/V9wU2P +GVom77zu8SZJuSFScKDV0XCmsm69TBCjdk7knulafWXvk4bD/vPL6ObIJTds8yh +f1lSejlxikNocp9vMtUDZt7AZS2MGyYW3wFoJz5MwVyNfNkX1+67/LBCqdvn+I2 xvMg30bbInoYuOZlzVkCdpSRoFXaHc4r0Tv3AXswNro3Ga8672I= =KWHJ -----END PGP SIGNATURE-----