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

On 4/22/2011 2:28, andrel wrote:
> 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.

That's why I'm telling you. :-)

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

Post a reply to this message

On 4/22/2011 3:09, andrel wrote:
> *) Some changes might trigger a tool to create a tool to be rebuild.

Just so you know, this isn't difficult in Windows. Heck, I don't even have 
to write the makefiles myself - the IDE does it. I have lots of data formats 
that I wrote my own compiler for that automatically gets compiled before the 
data that depends on them gets compiled.  Stuff like taking a bunch of 
frames for an image, automatically laying them out on a bigger sheet and 
storing the boundary information separately with an annotation that the 
boundary information depends on the constructed sheet and the constructed 
sheet depends on the individual frames and the program depends on the parser 
for the boundary information and the individual boundary information files 
and etc etc etc. It's not any harder (if not easier) to set up in Windows 
than Linux.

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

Post a reply to this message

On 4/13/2011 10:30 PM, Darren New wrote:
> Am I old, or is it really unprofessional to publish an API and have the
> official documentation for the function call be "go read this guy's blog
> from last June to see an example of how to use this API"? Even if the
> guy is the one that implemented it?

In the military in the 2000-01 timeframe they release the Job 
Qualification Standard for my specialty (small computers maintenance), 
and many of the training references were to websites.  Many of the web 
sites did not belong to the military, and some of them were no longer 
on-line when I went to read them.

Nice idea, until you try it.

Regards,
John

Post a reply to this message

On 22-4-2011 17:57, Darren New wrote:
> On 4/22/2011 3:09, andrel wrote:
>> *) Some changes might trigger a tool to create a tool to be rebuild.
>
> Just so you know, this isn't difficult in Windows. Heck, I don't even
> have to write the makefiles myself - the IDE does it.

The IDE's that I (superficially) tried when it was relevant (5-10 years 
ago) seemed not able to call ctangle before calling the c-compiler (it 
simply assumed you were writing C source directly). Let alone call 
cweave or mweave (our matlab frontend) to create the docs or mtangle and 
leave the results alone. I think some even created a makefile from 
scratch everytime, in order to make it impossible to tweak it yourself.
  Unfortunately also in that period I simply had no time for a full 
investigation, people had problems recording and analysing their data. 
And I could modify the matlab sources directly. Always planning to 
backport in the WEB files of course...

> I have lots of
> data formats that I wrote my own compiler for that automatically gets
> compiled before the data that depends on them gets compiled. Stuff like
> taking a bunch of frames for an image, automatically laying them out on
> a bigger sheet and storing the boundary information separately with an
> annotation that the boundary information depends on the constructed
> sheet and the constructed sheet depends on the individual frames and the
> program depends on the parser for the boundary information and the
> individual boundary information files and etc etc etc. It's not any
> harder (if not easier) to set up in Windows than Linux.

That might be. In Un*x it is simple a set of scripts and makefiles. 
Something I understand. IME in windows it was often hard or impossible 
to parse such script files. For some reason I quite often end up wanting 
to automatically change them, but that may just be me.

Things might have changed a lot since then. What IDE are you using?


-- 
Apparently you can afford your own dictator for less than 10 cents per 
citizen per day.

Post a reply to this message

On 4/23/2011 2:51, andrel wrote:
> Things might have changed a lot since then. What IDE are you using?

Visual Studio 2010 at the moment. It's all XML files.

Indeed, I have a data processor that you can say "this file compiles with 
the manifest processor", and each time you run the compile, the manifest 
processor parses the makefile to figure out what files go into the final 
build and sticks their names into a text file which it adds to the final 
build. The sort of thing you'd normally use directory enumeration at runtime 
to fetch, if you weren't sandboxed out of the directory access 
functionality.  So I stick in a file with the name "manifest", say "compile 
this with the manifest processor". The manifest processor gets compiled, 
then runs and looks at the makefile, pulls out the list of dependencies 
marked as "to be copied to the final distribution directory", and stores 
that into the manifest file, which then gets copied into the destination 
directory also (while leaving the manifest processor behind, mind).

The makefiles are all XML of dependencies and what commands to run, but 
there are few if any dependencies in the makefile on actual files per se. 
For each directory, there's a list of "these files should be compiled with 
those compilers" and a list of "this entire project depends on that antire 
project." It's mildly funky because before you can (conveniently) say 
"compile manifest.txt with the manifest processor" you must have already 
compiled the manifest processor once. Obviously that's an IDE limitation and 
not a makefile limitation, tho, since you can delete all the results and 
still do the recompile.

But most of the dependency analysis is done by the actual compiler as it 
compiles. For example, if you say "I want a house model, and it depends on 
the bricks texture and the wood texture", you don't put that information in 
the makefile. You put that information in the house model. When the 
processor processes the house model, it tells the build system that the 
house model depends on the textures, so if you change a texture after you've 
built the house, it rebuilds the house too. But you don't do that stuff 
manually - that's just silly.

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

Post a reply to this message

On 4/23/2011 9:42, Darren New wrote:
> So I stick in a file with the name "manifest", say "compile
> this with the manifest processor".

Oh, and if there's parameters specific to that compile (like, whether to 
compress images or something), they're represented as properties with an 
attribute set (basically, in the "javabean" kind of sense), and the build 
system looks at the executable after it's built in order to give the GUI a 
mechanism to prompt for which parameters need to be changed. It then records 
those parameters into the build file again in XML, and passes them to the 
processor when it recompiles anything in that dependency chain.

Overall, a very cool system. It just takes a bit of cooperation from the 
compiler to make it all work seamlessly.

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

Post a reply to this message

On 19/04/2011 10:31 AM, Invisible wrote:

> http://questionablecontent.net/view.php?comic=1144

Angus?

The Angus she eventually ended up hooking up with?

Oh, sorry - you guys don't care about that. I forget sometimes...

Post a reply to this message