|
Member 7989122 wrote: Lots of the examples in your link of poor commenting are not "poor", but outright silly
Then why have I seen them so often?
I don't like comments because you're supposed to write comments.
That's kind of a thing, you either write comments or you're a bad programmer who doesn't take pride in his work.
The result is that a lot of programmers write comments for the sake of commenting.
And then you get comments like product.Save(); // save the product
Which gets copy/pasted.
Or the code gets changed, but the comments don't.
Every comment is a line of code that has to be understood and maintained.
And sometimes the comment is more cryptic than the code!
That's because the code that needs to be commented, often can't be explained on one or two lines.
For public API's I'm a fan of using the /// kind of comments (what are they called?).
At least you'll see what a function and parameters do.
A parameter like "fileName" could have the explanation "Complete file name including path." and at least you'll know what's expected.
It could be solved by naming it fileNameInclPath, but that gets tricky quite fast.
|
|
|
|
|
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
