 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2011/04/20 17:53, Darren New a écrit :
> 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 which
>>> 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 an
>> 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
>> content and
>> index.
>
> I'm at a loss as to why such would be in comments in source code, but
> OK. :-)
>
It's pushing the concept of "the source code is the documentation" to
the extreme, and boldly entering the realm of absurdity ;)
To boldly code where no one have coded before :P
Alain
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 21-4-2011 4:31, Darren New wrote:
> 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.
I don't own the book. I only saw the page you linked to.
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 21-4-2011 18:33, Darren New wrote:
> 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.
I have used it in the past and in my experience it works extremely well.
Most importantly because both me and the colleague that were developing
a large package *enjoyed* writing nice documentation. Becasue the
documentation is generally on the level of small chunks (10-50 lines) we
tended more to document the why than the actual implementation
('increase counter by one')
I effectively stopped slowly when he left. He had it all nicely set up
on a linux box. With all sorts of interlocking make files and scripts*.
The Windows environment is more geared towards instant satisfaction.
Press a button and it will automatically build. Pity if you want
something done at some specific time during the compilation process, we
though about it and you (who we assume to be a below average user) don't
need that.
It is entirely possible that even in a Windows environment I might have
been able to get something workable in the end, but I did not have the
time and money to research it properly. Knowing that it is almost
trivial within the un*x way of thinking might have played a role.
When I switch to a linux box (that might be soon, because of ICT
department in the hospital**) I'll try to recreate such an environment.
*) Some changes might trigger a tool to create a tool to be rebuild. It
could cause a chain of extracting the C and Matlab files from a source
file. Call one of the matlabfiles to create an image for metapost, call
metapost. Include the resulting figure in the documentation. Rebuild all
documentation in pdf. Call one or more preprocessing steps on the source
(this might include lex and yacc). Build the tool. Find all files that
use this tool. Rebuild those too. Oh and everything under revision
control of course.
**) not because they want that. They actually want to force everybody to
use Windows machines. Simply because I cannot work the way they want me
to*** and using a Linux box will buy me a few years to proof they didn't
think through all consequences.
***) nor can the department afford the ridiculous pricing scheme they
try to force on us.
--
Apparently you can afford your own dictator for less than 10 cents per
citizen per day.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
