4 ms·
"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
by leothekim 14y ago
"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.
- cobrausn 14y agoNot all code is readable. Some of it always ends up being an ugly hack. If that ugly hack is not documented, I want to start punching previous developers. 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.
- sethetter 14y agoPerfect. There's always going to be an edge case, and with code there is always going to be some logic that can't be understood at first glance. Tests are great, but comments help too. As long as comments stay updated with code changes they are useful.
- scaryclam 14y agoComments can indeed lie to you, but code can also be doing something that was not actually intended. 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...