A bit of history (or archaeology ?) We are now back to the old times were we used to struggle about comments in the code.
When I started coding, code was "self-understandable" according to the legend, especially assembly code. If you could not understand the code without comments, you did not even merit the privilege of modifying it. That led to the God syndrome which I still suffer from today :))) Of course that's an extreme and that does not make sense most of the time. Having the ability to read and understand systems of 100,000 un commented code lines and above is great but you still have to work with teams of mere mortals if you want to achieve something significant today, so it's best to keep away from that drug :))))))))) There is a balance between the # of code lines versus the # of comment lines but it's more based on the quality of the comments and the language being used than the actual ratio. Assembly code required most of the time one comment every two lines, Lisp much more less. Today some will say, we have JavaDoc like tools to save us... The OO approach can lead to myriads of objects and that requires a tool just to navigate in all the references in the code. But that automation does not capture the essence, just the ground level details. JavaDoc is very verbose about the insignificant details but useless in understanding the core behaviour of all these objects floating around and their interactions because most developers do not want to write decent synopsis in each class with all these HTML tags. That's why we see all these books written on how to use this framework, this library, ... That's good for them, they get paid to write their comments in a book instead of the code, why not ? JavaDoc tries to fill the voids by spitting so many details of microscopic scope that I find it better to read the source code when available to get a better understanding on how the components interact. Here we typically in Clojure code use a module header comment block and a function comment block plus some single comment lines if the code becomes a bit obscure. Each module comment block has a number of items: title, synopsis, author, history and each function comment block contains a synopsis, warnings, ... We emphasize explaining what the major chunks do (modules, functions). Clojure being expressive, no need to get entangled in the details IF the module and function goals are described with sufficient details. In this context being concise in comments makes sense. You can read the code much more like a book, you just print it and that's it (I read on paper, never was able to stand reading documents on my computer screen for very long times). Of course, I used to write 30,000 lines of code and more using a simple text editor (no language sensitivity), a compiler, a text search tool (no regexp), a linker and it's cross reference facility... I am used to travel lean and this approach is similar to the one I used in the last 25 years:))) I remember a custom tool a customer wrote to extract the detailed specs document directly from the code comments and processing this in a text processor to obtain a clear and well formatted document. It also made the code quite clear to read as is. I totally agree no comments is not good at all but JavaDoc style comments in Clojure ? I pray you all, please stay away of it :)))) Luc On Fri, 2009-08-07 at 13:58 -0700, Tchalvak wrote: > As a Noob to clojure, one thing that scares me is the comment-to-code > ratio. I mean, the meaning that can be packed into clojure can be > immense, which is great, but it seems like that means that a lack of > commenting is all the more dire of a problem. The best commented > clojure code that I've seen so far is probably the github clojure > repository, and that seems to have devolved to the minimum comment > density of a single comment per function. Maybe I've just been > looking at the wrong pieces of clojure code, but so far it's been a > turn-off in the code that I've looked through. > > > > Luc Préfontaine Armageddon was yesterday, today we have a real problem... --~--~---------~--~----~------------~-------~--~----~ 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 Note that posts from new members are moderated - please be patient with your first post. 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 -~----------~----~----~----~------~----~------~--~---
