[ghewgill]

I agree that the title is ambiguous - it's what piqued my interest to read the article in the first place. Personally I lean toward fewer comments overall - perhaps to a fault - but explanatory comments as shown in the article are absolutely valuable. It's a good reminder to explain the whys and the why nots.

This especially applies to your own code that you write and still have to maintain 5, 10, 15 years later. Just the other day I was reviewing a coworker's new code and thought "why choose to do it this way?" when the reason was 10 lines up where I did it the same way, 8 years ago. She was following the cardinal rule of maintenance - make the code look like the existing code.

[sparrish]

> make the code look like the existing code.

This is so undervalued when maintaining an older codebase. Please, for the sanity of those who come after you - make the code look like the existing code.

[sbuttgereit]

"Please, for the sanity of those who come after you - make the code look like the existing code."

I think it's a great rule of thumb... but there are exceptions.

For example, Funnily enough I was reviewing some code just today written by someone else and that I'm going to be asked to expand on or maintain. It looks like this:

  var example1 = Object;
  var example2 = Object;
  var example3 = Object;
  ...
  var example147 = Object;
  

And then later there are corresponding variables assigned to different objects which are:

  var tempExample1 = <some object instantiation>;
  var tempExample2 = <some object instantiation>;
  var tempExample3 = <some object instantiation>;
  ...
  var tempExample147 = <some object instantiation>;

And this goes on and on. It's real special once we get into the real business logic. (and to be clear... "example1" are the actual names, I'm not just obfuscating for this comment.)

The reason it looks like this is because the original developer copied the examples from the developer technical documentation for what they were doing verbatim; this documentation only had one variable so the numbering was the way to get multiple variables. Knowing this system, they didn't have to do that, they could have very easily assigned meaningful names for all of this. (To be fair, the original developer isn't a developer but a consultant business analysist saying, "Oh yeah, I can do that!" to the client.... billing all the way).

I can tell you with great certainty and righteousness: I'm not going to make my code look like the existing code. I may well do some refactoring to make the existing code vaguely scrutable.

I appreciate that what I'm describing is an extreme case and not really what you or parent comments really were addressing. I just stop to point out that what you describe is a rule of thumb... a good one... but one nonetheless. And, as an absolute rule of thumb about rules of thumb, there are no absolute rules of thumb. Ultimately, experience and judgement do matter when approaching the development of new code or decades old code.

[PeterisP]

The concept of "make the new code look like the existing code" still applies - in the example you gave, if you need to add examples148-200, and want to do it in a better way, then it would be wrong to do that new way for the new code; either you are willing and able to refactor the previous 147 cases as well (so that the new code matches the existing code, because the existing code was updated), or you keep the existing structure.

[Tainnor]

Unless of course you work in a wild-west codebase where you can basically tell who wrote what code because everyone has a distinct style and they never converge. ugh