|
I worked on a project in need of a record management library. It would have to be open source, as we were going to extend it significantly. We found one that - according to the description - fufilled all our needs, so we got hold of it. Fortunately, it didn't cost us any money. The code was well commented, each function wiht a (presumably) descriptive heading, comments before loops and other control structs, and lots of end-of-line comments. But I can't comment on the quality of the code: It was all in French. All variable names were in French, too. None of the project members could read French.
So we had to go on searching for another library. Maybe we threw out the best alternative because of its comments. Maybe variable names in English and no comments at all would have made us go for it. And I didn't feel comfortable with the alternative that we settled on.
|
|
|
|
|
Not sure why you'd ever put them in documentation but there ought to be a law that says they should appear in sales brochures.
Whenever you find yourself on the side of the majority, it is time to pause and reflect. - Mark Twain
|
|
|
|
|
??
Ever try to use log4net or NLog without code examples in their documentation? That is just one example out of thousands for why "most" documentation needs code examples and example usage; especially if you are not used to working with the product, etc.
|
|
|
|
|
Yes, I see what you mean for API calls etc., examples are a must. I was thinking more of documentation for products where you don't get to interact with the code-base.
Whenever you find yourself on the side of the majority, it is time to pause and reflect. - Mark Twain
|
|
|
|
|
Never in a million years would I use a product whose doc didn't contain code samples.
cheers
Chris Maunder
|
|
|
|
|
That depends... You seem to be assuming that "documentation" means "documentation targeted at programmers". I can very well imagine documentation for an accounting system, a video editor or a computer game that does not contain code samples.
You may of course argue that "Clicking this button is the equivalent of calling an API, so for documentation purposes, illustrating the effect of clicking the button is a code sample". OK, I'll accept that, but to me that is twisting it quite a bit.
|
|
|
|
|
It depends on what is documented.
If it is an UI-Element it is useful when the documentation shows how it looks like.
Generally it is useful if the documentation shows and/or explains how it works ...
|
|
|
|
|
Exactly! Documentation should focus on the why much more than the how. What assumptions were made? What are the general inputs and outputs? What's the life expectancy of the application? What critical technologies are involved? Stuff like that. If organizations need documentation to explain the code itself (at least at a low level), then code is quite likely badly written.
|
|
|
|
|
I think
Is is comprehensive and covers every possible scenario (within reason)
should be
It is comprehensive and covers every possible scenario (within reason)
Amit Joshi
Value of the value is valued only if its value is valued.
|
|
|
|
|
It separates the Beginner and Advanced sections. That way, it is easy for both types of the users to look into.
Amit Joshi
Value of the value is valued only if its value is valued.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
