> sön 2008-04-20 klockan 22:14 -0600 skrev Alex Rousskov: >> The current suggestions are: >> <snip>
.h (as a second-best as .dox in src/) -- Amos >> .dox (in src/) -- Kinkie. >> .h (or perhaps .cc) -- Henrik. > > To clarify: > > Longer API documents, .dox file in docs/, or maybe src/ next to the .cc > > Basic rules the code need to fulfill, or until the API documentation > grows large, in the .h or .cc file. > >> P.S. BTW, I do not give much weight to "keep them close so that they are >> updated" arguments because in my experience documentation freshness >> depends on code review and the size of the comment, not its location. > > I disagree here, I find it a lot easier to make sure the basic > documentation is there if in the same file as the implementation. But > the Squid project is not a good example in either direction as we do not > have any history of actually keeping any kind of documentation up to > date, neither inline or in separate documents.. (only the opposite) > >> There are plenty of outdated comments in Squid sources, for example. > > True.. just as there is plenty of outdated code... > > But I usually kill them (both) these days if touching nearby code.. > > Regards > Henrik > >