"There is one source of truth in software, the code."
I agree with this statement wholeheartedly. Documentation starts with readable code. Comments can go out of date and, worse, lie to you.
I agree with this statement wholeheartedly. Documentation starts with readable code. Comments can go out of date and, worse, lie to you.
I wish people would stop taking these purist approaches. There is an obvious middle ground to this - document the non-obvious and your public facing APIs.
Having a comment to clarify intent is a saving grace when code looks correct but is doing the wrong thing. At least when a comment is conflicting with the code you know at once that you need to start asking questions...