3 ms·

> Each line of code was documented Wow. Every line. There is such a thing as too many comments or too liberal use of comments in code.

dx034 8y ago
Not if the system fails on a Monday morning at 3am after 20 years without issues and needs to be fixed before the business opens. Having comments for every line helps fixing it dramatically. For most code it will be overkill but there are some companies where it's integral for core systems.
- methyl 8y ago
  > Having comments for every line helps fixing it dramatically. That’s only true if comments are kept up-to-date. More often than not, they get out of sync with the code itself, causing even more confusion.
- Pamar 8y ago
  Honestly, these kind of problems are often due to unplanned/unexpected events (disk full, wrong permissions on a folder, OS updates correcting old bugs you have coded around) where having line-by-line comments would not help much if at all. I would love to work in a place where documentation was cosidered a valuable asset, but I think that your example is off mark.
- hellofunk 8y ago
  Sure but every line? You increment a loop counter, i+=1; and you say that in a comment? The best rule of thumb is, make the code so clear that it is itself a comment, and only if the code cannot relay the meaning, then add a comment.
  - injvstice 8y ago
    Depending on the code, it can be freaking hard to track down what that 'i' means, especially when someone writes a coding standard (or a language) where it requires all variables to be defined at the beginning of the function instead of close to location of use. on the other hand, if it was named something like number_of_records it would be clearer.
pjc50 8y ago
I doubt they meant literally every line, but for some of the more esoteric systems an average of one line of comment for line of code could be worthwhile. Paragraph of explanation, paragraph of code. I'm thinking of things like assembler or COBOL here. APL/J are highly compressed and any reasonable explanation would require more than one line of documentation per line of code. I know there's some J in financial institutions.
thisisit 8y ago
My bad, I should have been clearer. What I meant to say is each block of code was documented. So a logic change wasn't accompanied by line by line commenting rather a block comment explaining who, what, why and when of the change. The commenting guidelines were well defined too.

dx034 8y ago

Not if the system fails on a Monday morning at 3am after 20 years without issues and needs to be fixed before the business opens. Having comments for every line helps fixing it dramatically. For most code it will be overkill but there are some companies where it's integral for core systems.

methyl 8y ago
> Having comments for every line helps fixing it dramatically. That’s only true if comments are kept up-to-date. More often than not, they get out of sync with the code itself, causing even more confusion.
Pamar 8y ago
Honestly, these kind of problems are often due to unplanned/unexpected events (disk full, wrong permissions on a folder, OS updates correcting old bugs you have coded around) where having line-by-line comments would not help much if at all. I would love to work in a place where documentation was cosidered a valuable asset, but I think that your example is off mark.
hellofunk 8y ago
Sure but every line? You increment a loop counter, i+=1; and you say that in a comment? The best rule of thumb is, make the code so clear that it is itself a comment, and only if the code cannot relay the meaning, then add a comment.
- injvstice 8y ago
  Depending on the code, it can be freaking hard to track down what that 'i' means, especially when someone writes a coding standard (or a language) where it requires all variables to be defined at the beginning of the function instead of close to location of use. on the other hand, if it was named something like number_of_records it would be clearer.

pjc50 8y ago

I doubt they meant literally every line, but for some of the more esoteric systems an average of one line of comment for line of code could be worthwhile. Paragraph of explanation, paragraph of code. I'm thinking of things like assembler or COBOL here. APL/J are highly compressed and any reasonable explanation would require more than one line of documentation per line of code. I know there's some J in financial institutions.

thisisit 8y ago

My bad, I should have been clearer. What I meant to say is each block of code was documented. So a logic change wasn't accompanied by line by line commenting rather a block comment explaining who, what, why and when of the change. The commenting guidelines were well defined too.