My two cents... Comments are worse since Javadoc came to life, up to date or not.
Most of the time they do not describe the behaviour of the class in depth and you have to get the source code on your screen. We replaced quality by quantity. If I want to find the signature of a function I can always read the code, assuming I have access to it of course. I would expect much more from Javadoc than class fields and member function signatures but this would require discipline from dev people to add significant and useful comments in their code. Javadoc is an evil tool, it gives the impression that your system is documented because it easily spits out garbage... but it's only garbage, not worth anything when you're trying to fix a problem that requires a broader knowledge than the 25 code lines scope on your screen. In the mid 80's I and others in a Fortran dev. team created a super javadoc. This beast was spitting out a FULL document in the editor used by office people. You would write comments in the code that were extracted and you would get a readable well formatted document after running the tool. Without the comments, the document looked ... empty and ugly. Missing items were as obvious as a nose in a face. Easier for code reviewer to control that, no need to read the code, read the document. If it does not make sense then go back to the coder. Coders had to add decent comments since the conventions were not only based on what you extract from the code (like javadoc) but also what is expected in comments so the document text content gets filled with decent content. When you force the coder to enter comments to fil a chapter introduction, well he/she has no choice. Of course it looks like if creating code is twice as complex but in fact you saved time when you need a system to be described very precisely. It also insured that comments were meaningful and in synch. with the code. If no decent comments are added in the code, then were is the knowledge and how can it be shared ? After 20 years of dev, I dropped javadoc entirely, comments are now minimal (function description, oddities in the code) and I COMPENSATE with external doc (a real document). Why should I bother to get clear documentation in the code since most of the world out there does not care about it ? Best proof, almost nobody does it these days. External doc at least gives an explanation of the design and structure. It does not even have to be fully in synch with the code. Even outdated it is a better starting point for someone to learn how to navigate in application internals. You get a sense of what the designers wanted to achieve and how. Then when you get to code, it's much more easier because you have a broader picture and can make sense of what you are reading. You can review it once every year and that's enough. Most of the time you already have some basic material about the things that changed or were added. It's just a matter of reorganizing it. I fully agree ultimately code is the thing that runs... not your comments or your documentation. Many people still speculate about system behaviour from the comments they read and eventually derive plans from this. Bad mistake... go to the code for your own sake. Luc On Wed, 2008-12-31 at 08:41 -0800, Daniel Eklund wrote: > > This is the excuse continually trotted out by people too lazy to > > comment, or who think themselves superior to merely mortal programmers > > who have to work in teams and actually communicate with people. > > Redundancy in communication is almost never redundant; think of it as > > a checksum. <snip>.... > > A checksum should be trusted. Comments sometimes cannot. > > Since you brought up the issue with working in teams, I will submit my > decade and a half of experience coding in 'enterprise' team > environments (my chosen hell). I have built upon and maintained Java > code that has grown through accretion of various consulting > organizations, and I never trust comments. Even with third party > (supposedly stable) APIs, I have had (more than once) to open up the > code to discover that the javadocs are out of date and incorrect. I > do my bit; I try to maintain my comments, but I never trust. The code > IS the answer, always. > > > > 'Redundant comments are useless' is the mantra of the dilettante, the > > amateur, and the cowboy. > > I believe the मन्त्र 'comments are useless' is more cowboy-like, not > 'redundant comments are useless'. If not, what about the phrase > 'useless comments are useless'? > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~----------~----~----~----~------~----~------~--~---
