News for hackers. Stuff that matters.
Re:We fired our top talent. Best decision we ever made by valuearb on Saturday October 14, 2017 @11:39PM (#15475759)
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.

Given modern tools I’ve come to the conclusion that documenting overall purpose and specific edge cases is more than enough. For example, the file header should describe its purpose, and anything in the actual code that’s not obvious should be commented. No more boilerplate function or file comment header. Git tells me who wrote each line of code, I know the name of the funcs and files, and I can see the inputs/outputs for every func with my own two eyes.

Re:We fired our top talent. Best decision we ever made by sgift on Monday October 16, 2017 @10:38AM (#15483467)
> 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.

Re:We fired our top talent. Best decision we ever made by valuearb on Monday October 16, 2017 @04:29PM (#15486407)
I 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"