4 ms·
> I have been coding for almost 40 years and always been big on documenting code, but the problem is that code changes and documentation doesn’t always keep up.
by sgift 9y ago
> I have been coding for almost 40 years and always been big on documenting code, but the problem is that code changes and documentation doesn’t always keep up.
This has always been a sign for me to tread very, very carefully. People who change code without changing the comments probably didn't read the comments, didn't read the code or didn't understand it - either way, if comment and code disagree both are probably wrong.
- valuearb 9y agoI agree mismatched comments/code is a huge warning sign. But I think requiring standardized comments is a problem. When I started out every function had to have a header comment, with name, inputs/outputs, description of purpose/etc. It was significant extra work to keep that up to date. I could update a function three times in a day, and have to rewrite the comments three times to check it in. And in the end, I know the name of the function. I can see the inputs and outputs. The only part of those comments that were occasionally useful were purpose, details of which often changed with edits. And in reality, as long as the function isn't hundreds of lines long (another problem), I can read it and discern exactly what it's trying to do. Comments that were most useful said stuff like "this looks weird or dumb, but we had to do it this way because of this thing we and you probably didn't expect in the data/system/etc"