In our previous episode, Felipe Monteiro de Carvalho said: > > I'm not that fond of in-source docs. It has a certain principal appeal > > (maintaining both together), but I don't like the practice. Or at least the > > ones that I have seen. > > I find that the external documentation imposes a too big overhead. > When in-source I can write it in the same editor I am used to, > navigating the same source I am used to, instead of an external > representation of it. Not to mention when things get renamed external > docs usually have a hard time. I directly agree there is a navigation-to-docs penalty. Even if some editors/IDEs remedy that, there is a bump there.
> The external documentation duplicates information, because we already > describe how things work in the comments, and then we need to describe > that again in external docs. No. Only if you insist that all that be in the sources in the first place. (which is IMHO not the case if there are good external docs). Moreover it puts yet another pressure on the source files, which already has two permanent holy wars micromanaging each detail (formatting/identation and commit/VCS checkout behaviour, maybe the "don't let them be too big" is a third even) if you are in a team. If not, the comments in the sources reduce to warn for gotcha's and other notes, that might not belong in the docs at all. I don't see duplication a problem if they have two separate purposes. Or better: then it is not duplication. > Or if we don't comment properly it becomes hard to underderstand the code. Also not necesary, to study source, you could have a tool to combine the source with the external doc, with some crossref data. _______________________________________________ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
