4 ms·
This cannot be stressed enough. Often I see managers talk about Sharepoint or some wiki type tool within the company but then the culture of documentation is mi
by thisisit 9y ago
This cannot be stressed enough. Often I see managers talk about Sharepoint or some wiki type tool within the company but then the culture of documentation is missing.
The best case scenario I found was in a bank. Each line of code was documented and rationale explained in plain english. This way hypothetically even a newbie could run the system.
While different places have different issues, I found that the quality of documentation was inversely proportional to people's insecurity about their job. More insecure they were about their job. More resistance to documentation was found.
- hellofunk 9y ago> 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 9y agoNot 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 9y 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 9y agoHonestly, 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 9y agoSure 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 9y agoDepending 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 9y agoI 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 9y agoMy 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.