On 10/7/17 10:25 AM, John Maddock via Boost wrote:
Indeed, but there's another issue here I would like to raise:
* How do you know when a library is well designed?
The answer for me at least in part is:
* Can I, starting with a blank sheet of paper, easily explain what this does?
I've lost track of the number of times I've redesigned something because it failed that test.
WOW - Great minds think alike! I'm hoping you can find time to skip through the video of my presentation a CPPCon 2017 - if only so you can honestly endorse it. The short versions is a) normal process code, test then write documentation. Doesn't work. b) recommended process: Write documentation in parallel with design and coding. step 1: write one sentence description of what the library is meant to do. Step 2: make a simple illustrative example of how the library is to be used. If required make more examples. step 3: make the library to make the examples work. Step 4: fix library and examples so they make sense. Step 5: add notes. step 6: Fill in reference documentation using standard format - e.g. SGI format. c) This what I do and I think its extremely helpful. The main benefit is that I find design mistakes sooner so I have to do less rework. Second benefit is that final product is better and has list "added in" quirky features.
The problem I see then, is that tools that extract documentation direct from code have the effect of disengaging the authors brain from the task of explaining what their code actually does. Well it does for me anyway ;)
100% agree. I do agree that these tools might be helpful - but only up to a point.
I've also come to the conclusion that standardese does not make good documentation - despite having authored more than my fair share.
LOL - at least you've atoned for your sins. But really the standards have a different problem. Not so much as to help users, but more intended to help implementors. I would argue it's whole different problem.
And now I'll get back to lurking again.... John.
Right. What do we have to do to get you to make a conference appearance - if only to prove that you're an actual person rather than some robot, high school student, prison inmate with a life sentence or some thing else. Robert Ramey