4 ms·

> There is no more accurate documentation than the source code. "Accurate" needs unpicking. As the unambiguous representation of what the computer should do, y

> There is no more accurate documentation than the source code. "Accurate" needs unpicking. As the unambiguous representation of what the computer should do, yes. It is the sole source of truth. As the representation of what the author thought the computer should do, or does in fact do, it is wanting. This is why I dislike the StackOverflow style of snark where people tell others to just read the code, as a substitute for documentation. Documentation should record authorial intent, and also observations where intent might sometimes not be satisfied. The reader should be able to inspect code to determine for themselves whether it implements the intent or does not (in which case, a bug may be claimed). For example, if I write in the docs that foo(int bar) returns double the value of bar, that is intent. You the reader might inspect the code and see that there are cases where it does not. The author might also inform you that they know of cases where care must be exercised (eg bar is very large). OpenBSD manpages are examples of doing it right, by and large. They tell you what is supposed to happen, limits and issues that they know about, and you can get the source if you want to inspect things yourself.

GuB-42 2y ago
The code is not a substitute for good documentation, which is definitely the case for Qt. But unfortunately, it is not always the case. From hobby projects to internal company software, you'd be lucky to have documentation at all, and when you have, it is often outdated or just wrong. Popular, company-backed projects are usually good, as it is the case for Qt. Because companies have a budget for it, you need a budget, because good documentation is expensive, and generally not something people do "for fun". Prestige projects (GNU, BSD, etc...) may get good documentation "for free" as people who are not developers can get credits, but it is not a given. For example, Linux kernel internal APIs are poorly documented, that they are (deliberately) unstable probably doesn't help. The code is great though. At work, the first think I ask for when starting to work on a project is the source code, because documentation is almost always terrible (if it exists). And in the rare case where it isn't, that's when there is at least one person who is paid full time to do just that.

GuB-42 2y ago

The code is not a substitute for good documentation, which is definitely the case for Qt. But unfortunately, it is not always the case. From hobby projects to internal company software, you'd be lucky to have documentation at all, and when you have, it is often outdated or just wrong. Popular, company-backed projects are usually good, as it is the case for Qt. Because companies have a budget for it, you need a budget, because good documentation is expensive, and generally not something people do "for fun". Prestige projects (GNU, BSD, etc...) may get good documentation "for free" as people who are not developers can get credits, but it is not a given. For example, Linux kernel internal APIs are poorly documented, that they are (deliberately) unstable probably doesn't help. The code is great though. At work, the first think I ask for when starting to work on a project is the source code, because documentation is almost always terrible (if it exists). And in the rare case where it isn't, that's when there is at least one person who is paid full time to do just that.