Skip to main content
edited body
Source Link
J.G.
  • 335
  • 1
  • 8

Although there are one or two apparent points of disagreement among the existing answers, if only in emphasis, I'll try to summarise the usual advice in a way that makes clear where everyone's been coming from:

  1. Firstly, write clean code; any other "documentation" will take care of itself after that. Clean code is a whole set of principles to learn in the first place: single-responsibility classes, short methods that do one thing, good variable and method names, better class/type names than these by focusing on metaphors (e.g. call a MultiButtSupporter a sodasofa), unit tests to indicate requirements, DRY, SOLID, a consistent paradigm and so on.
  2. Code reveals how code works; comments reveal why code works. For example, explain a +1 with "prevents an off by 1 error", or some complicated formula with "derived in this textbook or webpage".
  3. Whatever you've been doing with comments, point 1 above may well achieve that in clean code. See comments as failures/necessary evils, or even lies if over time they get out of sync with code as both are edited. Comments shouldn't compensate for badly written code, because why would comments be written with any more talent or care than the code was?

On the other hand, if anything I probably err too far the other way, almost never using comments. Your code reviewers will let you know if you've got the balance in the wrong place for them, but if you make a conscious effort to follow the above 3-point plan you'll probably be close to their optimum anyway.

Although there are one or two apparent points of disagreement among the existing answers, if only in emphasis, I'll try to summarise the usual advice in a way that makes clear where everyone's been coming from:

  1. Firstly, write clean code; any other "documentation" will take care of itself after that. Clean code is a whole set of principles to learn in the first place: single-responsibility classes, short methods that do one thing, good variable and method names, better class/type names than these by focusing on metaphors (e.g. call a MultiButtSupporter a soda), unit tests to indicate requirements, DRY, SOLID, a consistent paradigm and so on.
  2. Code reveals how code works; comments reveal why code works. For example, explain a +1 with "prevents an off by 1 error", or some complicated formula with "derived in this textbook or webpage".
  3. Whatever you've been doing with comments, point 1 above may well achieve that in clean code. See comments as failures/necessary evils, or even lies if over time they get out of sync with code as both are edited. Comments shouldn't compensate for badly written code, because why would comments be written with any more talent or care than the code was?

On the other hand, if anything I probably err too far the other way, almost never using comments. Your code reviewers will let you know if you've got the balance in the wrong place for them, but if you make a conscious effort to follow the above 3-point plan you'll probably be close to their optimum anyway.

Although there are one or two apparent points of disagreement among the existing answers, if only in emphasis, I'll try to summarise the usual advice in a way that makes clear where everyone's been coming from:

  1. Firstly, write clean code; any other "documentation" will take care of itself after that. Clean code is a whole set of principles to learn in the first place: single-responsibility classes, short methods that do one thing, good variable and method names, better class/type names than these by focusing on metaphors (e.g. call a MultiButtSupporter a sofa), unit tests to indicate requirements, DRY, SOLID, a consistent paradigm and so on.
  2. Code reveals how code works; comments reveal why code works. For example, explain a +1 with "prevents an off by 1 error", or some complicated formula with "derived in this textbook or webpage".
  3. Whatever you've been doing with comments, point 1 above may well achieve that in clean code. See comments as failures/necessary evils, or even lies if over time they get out of sync with code as both are edited. Comments shouldn't compensate for badly written code, because why would comments be written with any more talent or care than the code was?

On the other hand, if anything I probably err too far the other way, almost never using comments. Your code reviewers will let you know if you've got the balance in the wrong place for them, but if you make a conscious effort to follow the above 3-point plan you'll probably be close to their optimum anyway.

Source Link
J.G.
  • 335
  • 1
  • 8

Although there are one or two apparent points of disagreement among the existing answers, if only in emphasis, I'll try to summarise the usual advice in a way that makes clear where everyone's been coming from:

  1. Firstly, write clean code; any other "documentation" will take care of itself after that. Clean code is a whole set of principles to learn in the first place: single-responsibility classes, short methods that do one thing, good variable and method names, better class/type names than these by focusing on metaphors (e.g. call a MultiButtSupporter a soda), unit tests to indicate requirements, DRY, SOLID, a consistent paradigm and so on.
  2. Code reveals how code works; comments reveal why code works. For example, explain a +1 with "prevents an off by 1 error", or some complicated formula with "derived in this textbook or webpage".
  3. Whatever you've been doing with comments, point 1 above may well achieve that in clean code. See comments as failures/necessary evils, or even lies if over time they get out of sync with code as both are edited. Comments shouldn't compensate for badly written code, because why would comments be written with any more talent or care than the code was?

On the other hand, if anything I probably err too far the other way, almost never using comments. Your code reviewers will let you know if you've got the balance in the wrong place for them, but if you make a conscious effort to follow the above 3-point plan you'll probably be close to their optimum anyway.