SV: SV: Regarding coding style
If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), there won't be any source code, except for method declarations. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. Now, i'm getting the signal that it's done in a different way in Python. I'm not sure how you concluded that from this thread. The below, more or less. :) What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Please note that i DO NOT argue against one way or another. I simply expressed surprise since i've been tought otherwise earlier and, maybe, there's a larger picture than what i've seen this far. As stated before, snakeology is a very new area to me. Yet. ;) -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: SV: Regarding coding style
On 2008-03-08, K Viltersten [EMAIL PROTECTED] wrote: If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), there won't be any source code, except for method declarations. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. The problem is that tools like Doxygen and JavaDocs generate warnings and errors and things if everything isn't documented completely. So you end up with a lot of silly boilerplate. I see this kind of nonsense a lot: /** * Get the width of a box * * @param box the box * @returns its width */ extern int box_get_width(box box); You are right that is it often useful to document what to pass to a method and what to expect back and that if this is done well in many cases it isn't necessary to see the implementation. But in many other cases it's obvious, and in other cases it's obvious if you just look at the source which you've got. What's needed is just a bit of common sense and pragmatism: APIs need more documentation if the source of the implementation isn't being released with them, and some APIs just need more documentation than others anyway. Python docstrings, like most things in Python, demonstrate this kind of common sense: you write what you want in them and as far as I can tell nothing complains if you don't write them at all. The lack of fascism is the big innovation. It sounds simple but it makes a huge difference: it's much easier to find (and keep up to date) the real documentation if it's not hidden in a forest of bogus documentation. -- http://mail.python.org/mailman/listinfo/python-list
SV: SV: SV: Regarding coding style
If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), there won't be any source code, except for method declarations. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. The problem is that tools like Doxygen and JavaDocs generate warnings and errors and things if everything isn't documented completely. So you end up with a lot of silly boilerplate. /** * Get the width of a box * * @param box the box * @returns its width */ extern int box_get_width(box box); Oh, yes. This is stupid. I agree with you. If one's supposed to comment, let him comment RIGHT. Otherwise, let it be. Usually, when i comment my code, it's a blessing. If not, i don't comment at all. You are right that is it often useful to document what to pass to a method and what to expect back and that if this is done well in many cases it isn't necessary to see the implementation. But in many other cases it's obvious, and in other cases it's obvious if you just look at the source which you've got. I agree. Sometimes, there's a demand from the customer to comment all methods. Then, and then only, i'll go commenting all. But i believe strongly that we think alike on this one. When it's suitable, it should be there. Otherwise - why bother. Right? The lack of fascism is the big innovation. It sounds simple but it makes a huge difference: it's much easier to find (and keep up to date) the real documentation if it's not hidden in a forest of bogus documentation. I couldn't agree with you more on this one! Thank you for an interesting discussion. -- Regards Konrad Viltersten sleep- a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
Re: SV: SV: Regarding coding style
On 2008-03-08, K Viltersten [EMAIL PROTECTED] wrote: If you can't/don't look at the source file, then comments aren't going to help (except in the case of something like docstrings in Python). I strongly disagree. Now, perhaps we're talking about different things, here? Usually, in the header file (C++), Header files are source code. there won't be any source code, except for method declarations. Declarations are source code. A common example: /** Projects an object from 3D to 2D using the method of Alexander The Great. \param 3D structure to be projected \returns 2D projection */ public Proj2D get2Dfrom3D(Proj3D param); That's source code. The above is, to me, very clear and consistent. Not to mention, easily handled with e.g. Doxygen to create a readable documentation. I've no problem with that. I don't see how this is dislikeable. Please explain. Perhaps the above IS what you ment by docstrings? http://en.wikipedia.org/wiki/Docstring http://epydoc.sourceforge.net/docstrings.html For Java, one has the JavaDocs, a great tool, provided one will comment each method and variable used. Now, i'm getting the signal that it's done in a different way in Python. I'm not sure how you concluded that from this thread. The below, more or less. :) What I really can't stand are the pointy-haired comment blocks at the beginnings of C/C++ functions that do things like tell you the name and return type of the function and list the names and types of the parameters. Please note that i DO NOT argue against one way or another. I simply expressed surprise since i've been tought otherwise earlier and, maybe, there's a larger picture than what i've seen this far. As stated before, snakeology is a very new area to me. Yet. ;) Duplicating information in a comment that is plainly obvious 5 lines below it in the actual source code is a waste of time when the code is written. A week later, the comment will be out of sync with the code and anybody paying attention to the comment will be mislead. I exaggerate (slightly), but in my experience anytime information is duplicated in multiple places it doesn't take very long at all before it's out-of-sync and incorrect in all places except one. -- Grant Edwards grante Yow! I'm using my X-RAY at VISION to obtain a rare visi.comglimpse of the INNER WORKINGS of this POTATO!! -- http://mail.python.org/mailman/listinfo/python-list
