 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/20/2011 11:33, Alain wrote:
> Le 2011/04/20 14:23, Darren New a écrit :
>> On 4/20/2011 10:37, Alain wrote:
>>> Comments, comments, comments and more comments.
>>> That's the only way that code can be used as documentation.
>>
>> Yep. And that assumes you know the right place to look in the code to
>> find the documentation. Without an overview, you wind up guessing whic
h
>> source files of which subdirectories you need to read for comments.
>>
>
> You start the main with a big comment block that contains an exaustive
> overview of the project. It's then followed by a table of content and a
n
> index...
>
> Then, each individual source files also contains a specific overview of
the
> function(s) of the following code, what kind of data it expect and what
kind
> of data it's expected to return. Don't forget the local table of conten
t and
> index.
I'm at a loss as to why such would be in comments in source code, but OK.
:-)
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 20-4-2011 23:53, Darren New wrote:
> On 4/20/2011 13:01, Jim Henderson wrote:
>> I have to admit I like that way of looking at it. :)
>
> Elegantly described in detail here, along with what to do about it:
>
> http://www.whyprogramsfail.com/
Suspiciously absent from the blurb is 'how to prevent them'.
Suspiciously present is a foreword by a MS employee.
Coincidence? you'll be the judge.
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/20/2011 15:07, andrel wrote:
> Suspiciously absent from the blurb is 'how to prevent them'.
Actually, the beginning of the book basically says "there's lots of books
about preventing bugs. This is a book about fixing them once they happen."
He's very clear about that.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 20/04/2011 22:53, Darren New wrote:
> I'm at a loss as to why such would be in comments in source code, but
> OK. :-)
Some people do advocate putting all your documentation inside your
source code.
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.)
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...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> 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.
Yeah, that's really not very appropriate.
>> 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.
I think we can perhaps summarise this:
Embedding the API reference in the source code might be a good idea.
Embedding the end-user documentation in the source code is a terrible idea.
As an aside, everyone in the Haskell world seems to document their stuff
using a tool called Haddock. Like Java's docgen (and presumably a
bazillion similar tools), it takes source code comments and builds an
API reference from it.
What it *doesn't* really let you do in a consistent way is write "this
is WTF this project actually does and how it's structured" type
documentation, which tends to be completely absent as a direct result...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> I would object to something like storing RFC822 as comments inside your
>> SMTP implementation.
>
> Yeah, that's really not very appropriate.
I may be incorrect here, but didn't Knuth embed The TeX Book in the
source code for TeX?
(This would IMHO fall under the category of "utterly inappropriate".)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/21/2011 8:37, Invisible wrote:
> Embedding the API reference in the source code might be a good idea.
> Embedding the end-user documentation in the source code is a terrible idea.
Embedding overview-for-maintainers as comments distributed throughout the
project is a bad idea. Embedding code samples as comments in the source
code is a bad idea. Embedding design decision discussions as comments is a
bad idea.
> What it *doesn't* really let you do in a consistent way is write "this is
> WTF this project actually does and how it's structured" type documentation,
> which tends to be completely absent as a direct result...
That's precisely my point.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/21/2011 8:39, Invisible wrote:
>>> I would object to something like storing RFC822 as comments inside your
>>> SMTP implementation.
>>
>> Yeah, that's really not very appropriate.
>
> I may be incorrect here, but didn't Knuth embed The TeX Book in the source
> code for TeX?
Literate programming is something different. In that case, you simply have
one file that has both the compilable code and the documentation discussing
it, with a tool to extract the two. If you have a programming language in
which comments are *designed* to generate books with tables of contents and
all that sort of stuff, and what you're documenting is the process of
writing the code, then sure, that's not bad.
That's not what I'd consider "comments in the code", tho.
--
Darren New, San Diego CA, USA (PST)
"Coding without comments is like
driving without turn signals."
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> I may be incorrect here, but didn't Knuth embed The TeX Book in the
>> source code for TeX?
>
> Literate programming is something different.
>
> That's not what I'd consider "comments in the code", tho.
I'm not sure what the difference is.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
