On 4/21/2011 1:11, Invisible wrote:
> On the one hand, the idea is that the documentation is more likely to stay
> in sync with the source code. (E.g., if you swap the order of the arguments
> to a function, the documentation is right next to it, so you can update that
> as well.)

I have no problem with that for how the source code works.

I would object to something like storing RFC822 as comments inside your SMTP 
implementation.

> On the other hand, your source code is now littered with miles of text which
> have nothing to do with the compiler error you're now getting...

Which also forces a recompile every time you change it, and means anyone 
writing (or reading) technical documentation has to have access to the code, 
potentially breaking stuff when they accidentally modify the file.

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message