For me, external documentation is the absolute worst scenario. It takes me at least 4 times longer to read through and understand code without comments explaining in English what's going on. Here's a real-life example:
// Toggle between Dropdown and Text
if(_protected.fields[field].fieldType() === "Dropdown") {
_protected.fields[field].set("fieldType", "Text");
} else {
_protected.fields[field].set("fieldType", "Dropdown");
}
I think it would take me about 4 seconds to figure out that this code "toggles between Dropdown and Text" if the comment weren't there. Since the comment is there, I can just glance at the code and understand immediately what it does.
toggleDropdown(field) {
if ...
}
toggleDropdown(_protected.fields[field]);
Also the external documentation wouldn't have anything like this in it. It would be pretty much:
UI Code is in XXX. It communicates with ZZZ using YYY.
Fields in the UI are changed between text and dropdowns
depending on the value in the database that comes
from ZZZ. etc.
