Andy,
Here's a first sample -- I figure we'll either agree or agree to disagree before putting too much effort in. I wrote this to replace the class comment for Array. It could also be used in "About" methods, help, tutorials, and so on. IMHO it's way more helpful than the existing class comment. Further improvements welcome. 'Array is the simplest data structure beyond a single variable. Imagine a row of numbered jars. You can put any object in any jar using at: aJarNumber put: anObject. You can view the contents using at: aJarNumber which must be an integer. Arrays have the limitation of being fixed length. You can define virtually any length with Array new: size. More complex data structures use Arrays to hold their variables and grow by copying to a bigger Array or organizing groups of Arrays. Arrays can be used in loops. array do: [:jar | "action on individual jar contents"). For more information on Arrays be sure to see the Help reference and tutorial information.' Kirk |
Suggestion for class "about" methods.
I've noticed some goodies have about methods which contain the standard copyright notice and that's all, absolutely no help whatever. I started using about methods during Digitlalk days when there were no such thing as class comments as a place to save some class purpose and post-construction analysis information. Here's a small example: about "Page methods copyright (c) 2000, Expertek all rights reserved" "Page is a quantized unit of disk space in a linked list to hold node or blob objects of varying size. When a page is called into cache by a BTree, it assembles the whole object from the list and when written it chops an object into a list of pages. Page holds these objects: content - one node with keys & data or blob object nextPage - pointer to next page of content or nil (on disk only) position - pointer to disk position (not saved) " This documentation could of course be placed in class comments now. But it has a certian attractiveness not included in my previous Array class comment in detailing how specific instance variables are used and how the class interrelates to other classes in the intended application. It does not have simple usage help though. These examples can be discussed and perhaps we can derive a moderate standard for what constitutes "useful" class documentation as opposed to the other kind. Regards, Kirk |
In reply to this post by Kirk W. Fraser
Here is a brief discussion of documentation theory including why Patterns
suck and should not be pursued. Also, I'm taking the liberty of bringing forward Bill's salient remark on why we need documentation, which is: "And the cost of not doing it? IMHO, the new code that I'm seeing is going to put the cost on the back end. And I'm not sure I'm comfortable with the analogy to strong typing. That's perhaps in part because I don't expect comments to be error-free; sometimes it's helpful to know what the developer thought at some point in time (for formulating theories about what might be wrong) or something close but not quite right might make the updated code easier to understand." - Bill Schwab. So far we have these types of documentation content proposed: 1) A practical statement about why the class exists. 2) How to immediately use the class stand-alone in interesting ways. 3) How the class is used in combination with other classes. 4) Developer's thoughts (for ideas on what might be wrong). 5) Owner Copyright information - (assumed for packages?). 6) Instance variable content documentation. 7) Usage assumptions - what must be true to make it work. 8) Notice that the class is an Ansi Smalltalk Standard Class or not. Any further ideas as to what constitutes useful documentation that is brief and easy to maintain? Should we extend the list or can we prune the list without losing helpfulness value? -------------Patterns Exposed----------------- Notice these class documentation values do not (and hopefully will not) include "Patterns." That is because patterns are not specific algorithms nor helpful documentation. Patterns are just unnecessary style suggestions which are better left to an integrated methodology like Extreme Programming or a company style manual. One of Smalltalk's interesting research and development issues was the creation of the object paradigm which necessitated the paradigm shift in all other viable programming languages. But the essence of a paradigm is a new perspective or viewpoint consisting of redefined words that essentially mean the same thing. Value was present because objects do make it easier to program. Like the object paradigm shift, the shift to Extreme Programming started with Smalltalk and is percolating through other languages because it makes programming easier. Many people were fooled by the snake-oil of the patterns paradigm because "patterns" sounds important like "objects" and the books of patterns were far easier to write than tested algorithms so quite a few were written. But unlike patterns for cutting out clothing, these software patterns did not make it easier to write programs. That is why patterns have gone away except for a few diehards who still believe the pattern paradigm hype. ----------------------------------------------------- Further discussion on documentation that would actually help make programming easier is encouraged!!! Kirk Fraser |
In reply to this post by Kirk W. Fraser
Kirk W. Fraser <[hidden email]> wrote in message
news:bAnB9.26960$A%[hidden email]... > Andy, > > Here's a first sample -- I figure we'll either agree or agree to disagree > before putting too much effort in. I wrote this to replace the class > comment for Array. It could also be used in "About" methods, help, ... This sounds good except I am not sure about the reference to "numbered jars". Your comment would be great for someone totally new to programming (and maybe that is a good idea after all), but I am not sure if it is a little too detailed for a class comment in the image. I don't think the "For more information..." bit at the end is necessary, unless it referred to a specific source. If it included code to open the manual on Array documentation it might have value. Also the comment should explain that Array indexes are 1 based. Chris |
In reply to this post by Kirk W. Fraser
Kirk W. Fraser <[hidden email]> wrote in message
news:eEuB9.26967$A%[hidden email]... > > So far we have these types of documentation content proposed: ... > 4) Developer's thoughts (for ideas on what might be wrong). I am not sure if this needs to be a specific item. If all other points are documented then we may be able to infer what the developer was thinking. Perhaps this could be an optional item, added only if it adds value to the comment. > -------------Patterns Exposed----------------- > > Notice these class documentation values do not (and hopefully will not) > include "Patterns." That is because patterns are not specific algorithms > nor helpful documentation. Patterns are just unnecessary style suggestions > which are better left to an integrated methodology like Extreme Programming > or a company style manual. ... Gee, what did patterns ever do to you? ;) I am certainly not a Patterns expert, but I do find some value in them. I don't believe that everything needs to be distilled into a pattern. However I think I have benefited from reading about some patterns, and I think they are a useful communication aid. Are you saying that it would be bad to make reference to a class being a Singleton or using a Wrapper pattern in the class comment? I think these are useful descriptions as they help me understand how the class works on an overview basis without having to study the implementation or documentation closer. I am not implying that a pattern reference should be used instead of documentation, but I don't think it hurts the documentation to have it either. I think in moderation patterns are useful. Perhaps they may have been abused by some. So has cough syrup, but that doesn't make it inherently evil. Chris |
In reply to this post by Kirk W. Fraser
Kirk W. Fraser wrote:
> Here's a first sample [snipped] Hmm, I'm not at all sure that I like this. (Personal opinion of course) I think you/we need to distinguish between two rather vague concepts: between "tutorial" information and "developer" information. I don't claim there's a really clean distinction between them, but it's more of an axis along which any given bit of documentation can be placed. I'd say that the image is no place for tutorial comments -- the writer of class comments can *and should* assume that the reader understands Smalltalk basics. So while I think text like yours has a useful place in the overall documentation, I don't think the Array class comment is the place for it. Actually I think you've chosen a rather unfortunate example -- Array, perhaps uniquely in the whole image, doesn't seem to require a class comment at all. However, for expository purposes, lets pretend that it, and the way it behaves, are not part of the Smalltalk underpinnings, but that it's a new optimised Collection class that Blair has just introduced in the latest release of Dolphin. What would the comment need to say then ? Well for a start it wouldn't need to say that it held integer-indexed slots, accessed by (1-based) #at: and #at:put:. These qualities are intrinsic to SequenceableCollection. Nor, by similar reasoning, would it be appropriate to mention #do:, etc. What the comment should say is how Array differs from its superclass (what new features it offers), what restrictions it imposes, how it relates to similar classes, and anything "odd" about it (i.e ways in which it doesn't behave like a typical Collection. (I'm not claiming that that list is sufficient or ideal for *all* class comments, more of that later.) So, I think an appropriate comment (if one were needed) should read something like: ---------------------- Array is a <SequencableCollection> optimised for very fast lookup via #at: and #at:put:, but at the cost of automatic resizing. Unlike most other Collections the size of an Array is not determined by how many items have been added, but instead is fixed when the Array is created, and can only be changed thereafter by the #resize: message. The slots of an array initially all hold nil. Because the size does not vary automatically Arrays do not implement the Collection>>add: method. Note that not all Smalltalk implementations allow Arrays to be resized using #resize:, so code that is intended to be portable should avoid using it. Arrays can be created by the compiler as literal expressions like #(1 2 3 4) or #('this' 'is' 'an' 'Array'), a particularly useful example is the empty Array, written #(). You should treat all array literals as immutable. See OrderedCollection for a Collection that is similar to an Array but which is automatically resized as items are added and removed. ---------------------- (The wording could be improved, but I think the content is about right.) A similar comment for OrderedCollection, that provides parallel information and also refers to Array, is left as an exercise for the reader ;-) For classes which are not embedded in a well-known framework, it would be appropriate to provide more information. The thing to consider is the need of the reader. Some classes are so obscure that a 1-liner is sufficient. Others form difficult-to-understand elements of complex frameworks, and long comments giving examples of use, references to other classes, etc, are almost mandatory (e.g. the Command classes -- which b.t.w do have decent comments, although still rather hard to follow). Most classes fall somewhere between these two extremes, and have intermediate requirements for "ideal" comments. I don't particularly like the "checklist" approach to comments of any sort (Kirk didn't advocate any such thing, I know, I'm just rambling on). It tends to lead to lazy comments that minimally fulfil the requirements defined by the list, but which provide no useful information at all. Repeating myself: the programmer writing the comment has to consider the needs of the reader. Basing the decision on what to document on what some "standard" requires, what is less-than-obvious to the programmer him or herself, or on what is not obvious from the code will all lead to bad commenting. I want to expand a little on that last point. It is frequently claimed that documenting what is obvious is a waste of time. I don't agree fully, for two reasons. One is that I've never seen it put forward in real life (i.e. where I knew the programmer and had seen his code, and well as hearing the opinion expressed) where it wasn't just a cover-up for laziness. A touchstone for whether the programmer is being "lazy" when applying the if-its-redundant-then-leave-it-out rule, is what they do in the cases of doubt. My own experience is that programmers who claim that their code doesn't need (many) comments *invariably* write code that does need (more) comments -- it just doesn't have (enough of) them. The second reason is perhaps more interesting. I dispute the unspoken assumption that redundancy is bad. Redundancy in *code* is certainly bad, "once and once only" is an excellent guideline. But redundancy in *communication* is desirable and often necessary. Explaining something in two ways is better than explaining it in one. Stating something twice (in two way) is more reliable than stating it once. That's my last substantive comment in this post. I'm going to finish with a little story, but if you think I've waffled on more than enough already, then you can skip it without loss... -- chris ============= How I Once Nearly Destroyed the Firm I Worked For. Some years ago I was working for a small company that had just landed a really important contact. The contract was the biggest the company had ever had, and was for software for a big new spin-off operation set up by a potentially valuable new customer. My employers had tendered at a very low price (I think less than break-even) because getting the contract would open up a lucrative new market -- not just the new customer but a whole market sector. A deliberate gamble. Naturally, the tender was based on the initial estimate of what was required, and naturally that estimate was too low. By a factor of about 4. Since even the initial estimate called for using most of my employer's resources for about a year, this meant that they were in serious bother. I had very little to do with all that, I was just a programmer (working in C, which gives you some idea how long ago this was :-) I had quite a responsible job, though -- I was writing stuff that was central to the viability of the operation itself. It *had* to work. It didn't. The customer had been well pissed-off anyway. We were running unacceptably far behind schedule (remember the initial estimates were way off). We had been forced to employ a large number of (very expensive) contractors to try and get things done in something like the available time, and what with that and the pressure, the bug-counts were way too high. But then, on top of all that, the key function was failing intermittently, and -- after some months -- still nobody had a clue what was causing it. I don't say it was *very* likely, but it was certainly on the cards that the customer could just cancel the contract, and either cancel or postpone the new spin-off operation. If that had happened then my employer would have gone under. One day, one of the other programmers was reading though my database initialisation code and he noticed something roughly like: /* * set the isolation level to read-repeatability; that's the default * anyway, but just to be sure */ if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK) ... A completely redundant comment (unless you consider that the horrible identifiers chosen by the third-party database vendor made them necessary -- I didn't at the time). He noticed that the comment didn't match the code -- the parameter should have been ABC_ISL_RR. Because of this, my code wasn't running with the isolation level it had been designed for, hence the intermittent failures. With that fixed, the problem, and the biggest threat to the project, went away. The story has a happy ending: we did manage to get enough delivered to the customer that they could open the spin-off on the date they had set. They made money on it. So they were happy with us, and stayed with us for further developments, so we also made money, and eventually the project showed a profit. We did get an entry into the new market segment, and the company (who I left ages ago, though I stayed for some years after the time of this story) went on to make lots of money and expanded considerably. And the moral of the story ? It could be something about project planning, it could be something about proper choice of identifiers, but I think that it also shows just how valuable commentary can be, and especially that redundant comments are a Bloody Good Thing. -- chris |
<snip>
> /* > * set the isolation level to read-repeatability; that's the default > * anyway, but just to be sure > */ > if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK) > ... </snip> I think I sit firmly on the fence. I feel a comment here was not redundant - there is nothing obvious about the fact "abc_set_is_lvl" is setting the isolation level of a relational database (well, perhaps the context around it), nor is it at all obvious that "ABC_ISL_RR" vs. "ABC_ISL_RP" means repeatable read. Kudos for you for documenting the arcane nature of these variables. The "you don't need comments" camp (and I think you need class level comments anyway, plus a good class diagram, plus a class library overview) has a lot of it's genesis in the Smalltalk world. It might be easier to do in Smalltalk than C, although a lot of the lessons I've learned in Smalltalk might potentially be utilized in C. For argument's sake, let's say we have a class that represents the database connection: DBConnection, that wrapped the calls to the DB library. Then, you would have written something like: ============== logonWithUser: aString password: aString2 ... various logon stuff here .... self setRepeatableRead. ... ============== setRepeatableRead self setIsolationLevel: RepeatableRead ============== setIsolationLevel: anIsolationConstant | result | result := self database isolationLevel: anIsolationConstant. result = OK ifFalse: [self dberror: 'Set Isolation Level Failed'] ============== Now you would have to check that your pool of DB Constants was correct: OK=0 NonRepeatableRead=>0 RepeatableRead=>4 or whatever. The pool creation code *should be documented*, because this is where you touch the external system and where the "cryptic code to self documenting pool variable" mapping occurs. Smalltalk, with it's keyword parameters, lends itself to documenting what methods do in the method naming. Its flexible refactoring makes it easy to break chunks of code into methods that, in turn, name what they do (especially any Smalltalk with the Refactoring Browser, like D5). Just my 0.02 - and thanks for sharing your experience - I find this topic very interesting. I often wonder how much I can take my Smalltalk experience reducing comments to other languages - I just did a VisualBasic.Net project and found some difficulties (overloaded method names comes to mind) but also was able to use many of the techniques I had developed writing Smalltalk. jlo |
In reply to this post by Kirk W. Fraser
"Kirk W. Fraser" <[hidden email]> wrote in message news:<eEuB9.26967$A%[hidden email]>...
> Further discussion on documentation that would actually help make > programming easier is encouraged!!! This thread seems to be about how one should write class comments. To my mind, "documentation" is something broader. It may include class and method comments, but it also includes user's guides, tutorials, API descriptions, reference guides, tools reference, on-line help, etc. What audience are you trying to reach? Experienced programmers? Beginners? Class comments are not really the place to try to reach beginners. If the goal of making programming "easier" means "making programming easier for beginners", then it might be worth thinking about other forms of documentation that are directed at a broad audience. For example, consider the books offered by a publisher like O'Reilly & Associates, and look at the titles for PHP and Python. What would it take to get a similar title published for Smalltalk? M. Roberts |
In reply to this post by Jeffrey Odell-2
Jeffrey,
> <snip> > > /* > > * set the isolation level to read-repeatability; that's the default > > * anyway, but just to be sure > > */ > > if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK) > > ... > </snip> > > I think I sit firmly on the fence. <grin> > I feel a comment here was not > redundant - there is nothing obvious about the fact "abc_set_is_lvl" is > setting the isolation level of a relational database As I look back on it I agree, but at the time, when the code, and I, and my colleges, were all steeped in the API to the database, it certainly felt redundant. I wouldn't have used the comment if it weren't for my habit of commenting code so that it can be followed *without* reading the code. (We're talking about C, here, -- I work slightly differently in Smalltalk). > For argument's sake, let's say we have a class that represents the database > connection: DBConnection, that wrapped the calls to the DB library. Then, > you would have written something like: [snip] For comparison, here's how it might turn out if I were coding it: ============== setRepeatableRead "set the database connection's isolation-level to 'repeatable read'. Note that changing the isolation level will close any open cursors. Also note that this mode is the default for a newly opened connection" self setIsolationLevel: ABC_ISL_RR. ============== setIsolationLevel: anInteger "private -- set the connection's isolation level to one of the modes defined by ABC_ISL_* constants" (self database isolationLevel: anInteger = ABC_OK) ifFalse: [self dberror: 'Set Isolation Level Failed']. ============== One minor difference is that I prefer to use the documented names of third-party constants at the bottom-most level, which both adds to and reduces the self-documenting effect. You'll notice that the comment on #setIsolationLevel: is almost redundant. I agree that it is. However it helps me make a point -- if I weren't in the habit of commenting *all* methods, then I'd probably not have commented that one, but I *also* (not being in the habit) probably wouldn't have thought to comment #setRepeatableRead either, and its comment is definitely not unnecessary. > Smalltalk, with it's keyword parameters, lends itself to documenting what > methods do in the method naming. Yes I agree with this, and the method name does provide a useful source of the redundancy that I was advocating. However, in the example above, to get a reasonable level of self-documentation, I think that the method would have to be renamed to either #setConnectionIsolationLevelToReadRepeatability, or #setIsolationLevelToReadRepeatability (depending on which it actually did). It could be argued that these are better method names anyway, but for my taste they are too long and carry too much explicit context around with them, extra baggage that makes the sender code clumsy. Since you've said you are interested in this topic, I'll risk a further tangential waffle. I suspect that the "top-down", or "caller-driven", way of working leads naturally to a tendency not to comment code much. If you are using programming-in-the-debugger, or are doing test-driven coding, then whenever you reach the point of writing a particular method, you will naturally have a complete "context" in the foreground of your awareness. You'll have a complete picture of what responsibility the method is intended to discharge, and what the dynamic call sequence is that reaches the method. This is information that the *reader* of the code won't have (unless they are using the debugger to explore the code). I suspect that as a result the "top-down" programmer will tend to document less of that context, either because it is so obvious *to him*, or (if he believes in the value of comments and is being conscientious) because doing so provides no real value to him at the time -- i.e. the comment is all cost, no personal benefit. I don't like the caller-driven way of programming myself (I've nothing against other people who use it -- except the above suspicion -- but I find it hampers my ability to create abstractions). I like to conceive a "role" or a set of responsibilities" and create a class or group of classes that constitute a machine for discharging those sorts of responsibilities. Later on, I'll write higher-level code that makes use of that machine. That means that when I'm coding any particular method, my focus is more on the way*s* it is intended to be used, since I am -- by creating the method -- attempting to design a facility for others (and me) to use. Since that's how I'm thinking, I don't find that commenting a method is a nett cost (usually). The comment is not only there for other people to read, but is also there as my "working notes" on my design as it evolves. The comment helps me to think, and as such is a benefit to me personally and immediately. Anyway, getting sort of back on topic, that's part of the reason that I don't have a lot of sympathy for Andy's position that providing decent method comments is "too expensive". (I agree entirely that "glossy" documentation would be an unwarranted waste of resources, however.) -- chris |
Interesting ideas - I think I fall in
<snip> > I suspect that the "top-down", or "caller-driven", way of working leads > naturally to a tendency not to comment code much. If you are using > programming-in-the-debugger, or are doing test-driven coding, then whenever you > reach the point of writing a particular method, you will naturally have a > complete "context" in the foreground of your awareness. You'll have a complete > picture of what responsibility the method is intended to discharge, and what > the dynamic call sequence is that reaches the method. This is information that > the *reader* of the code won't have (unless they are using the debugger to > explore the code). I suspect that as a result the "top-down" programmer will > tend to document less of that context, either because it is so obvious *to > him*, or (if he believes in the value of comments and is being conscientious) > because doing so provides no real value to him at the time -- i.e. the comment > is all cost, no personal benefit. > > I don't like the caller-driven way of programming myself (I've nothing against > other people who use it -- except the above suspicion -- but I find it hampers > my ability to create abstractions). I like to conceive a "role" or a set of > responsibilities" and create a class or group of classes that constitute a > machine for discharging those sorts of responsibilities. Later on, I'll write > higher-level code that makes use of that machine. That means that when I'm > coding any particular method, my focus is more on the way*s* it is intended to > be used, since I am -- by creating the method -- attempting to design a > facility for others (and me) to use. Since that's how I'm thinking, I don't > find that commenting a method is a nett cost (usually). The comment is not > only there for other people to read, but is also there as my "working notes" on > my design as it evolves. The comment helps me to think, and as such is a > benefit to me personally and immediately. > <snip> In Smalltalk, I fid myself creating a picture of the class and/or group of classes, but once I find myself on one particular class, I tend to be top down. I don't think this leads to less comments by nature of "knowing where I am at the time", but I do think it leads needing less comments. That's why I think a group of classes needs a "subsystem" description (think Ken Beck's original SUnit write-up - short, but without it you would have a harder time using it) and a class comment is a good idea for all classes. After that, method comments are as necessary. However, I'd always rather have my folks err on the side of too may comments than too few ;> jlo People tell me they find my code readable, and sometimes it does not |
In reply to this post by Chris Uppal-3
Chris,
It surprises me greatly how C programmers (including me up until I learned Smalltalk) are willing to use "unwrapped" functions and constants like this. In any mission critical development I would have to recommend some sort of abstraction level or at least a simple remapping of these abbreviations to something more meaningful, much in the way that your Smalltalk examples show. This should result in "executable comments" that by design may not become obsolete. For example, the original #include "abc.h" if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK) could be turned into #include "myabc.h" if (abc_set_isolation_level(db,ABC_ISOLATION_LEVEL_READ_REPEATABLE)!=ABC_OK) with myabc.h containing #include "abc.h" #define ABC_ISOLATION_LEVEL_READ_REPEATABLE ABC_ISL_RP int abc_set_isolation_level(DB db,int isolation_level); and somewhere such as myabc.c #include "myabc.h" int abc_set_isolation_level(DB db,int isolation_level) { return abc_set_is_lvl(db,isolation_level); } That doesn't seem to be the C way, but it might work better. If the one level of indirection is too expensive for production, then after everything is debugged, change int abc_set_isolation_level(DB db,int isolation_level); to #define abc_set_isolation_level abc_set_is_lvl Keith Chris Uppal wrote: > [snip] > > One day, one of the other programmers was reading though my database > initialisation code and he noticed something roughly like: > > /* > * set the isolation level to read-repeatability; that's the default > * anyway, but just to be sure > */ > if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK) > ... > > A completely redundant comment (unless you consider that the horrible > identifiers chosen by the third-party database vendor made them necessary -- I > didn't at the time). He noticed that the comment didn't match the code -- the > parameter should have been ABC_ISL_RR. Because of this, my code wasn't running > with the isolation level it had been designed for, hence the intermittent > failures. With that fixed, the problem, and the biggest threat to the project, > went away. > [snip] > -- chris |
In reply to this post by Jeffrey Odell-2
I tend to like the idea of enough documentation that you don't have to read
the code, especially for arcane classes where I don't know what is going on at first. That implies both class and method comments. As a Smalltalker, I know every class has methods which communicate with each other by message passing, parameter calls, and so on. It is like a pre-mix framework to build a personalized house on. Once you have analysed your problem enough to create a reasonable set of classes, instance variables, and methods, then it gets back to good old coding with generate and test to mesh the working code around the framework of classes and methods. So we could identify in comments what the framework is supposed to do with readable comments long before it actually works. XP's emphasis on refactoring tells me that we should change the framework often until we reach a working solution. The idea is to better integrate the code which does the real work with the framework to minimize everything. With very meaningful class and method names, this would reduce the need for explicit comments. But for the newbie to a package, whether it is part of Dolphin's base classes or something purchased from a third party like ST3D, there is still considerable need to be introduced to what is going on. Take ActiveX for example. As posted in another thread, I know nothing about it. I am told that working with it is the way to get my webcam to send its pictures into Smalltalk for processing. I can argue the language developers "should" provide integrated access to all common peripherals as a standard feature but that won't make it happen. So I have to learn to use ActiveX. Take a look at the ActiveX classes. If you don't know anything about ActiveX, you need new programmer information, not "developer" information. You certianly don't care that Beck's best practices were performed in creating those classes which makes them self-documenting to those who are in the know about ActiveX. You need simple step by step newbie level documentation on how to use the features available. So consider the reader -- if anyone needs to read the documentation, they probably need a great deal of help. If they just need a refresher, they can employ speed reading. There should not really be a difference in documentation levels for different users, preschool or Ph.D.. Some documenters make a big difference in documentation over time. I once worked on an old CDC mainframe to convert to IBM and I found that early operating system manuals were very helpful on the basics while later manuals were helpful on the new advanced features but ignored discussing the basics. I would of course like to see both covered well. The manuals themselves didn't make me a whiz at upgrading systems prior to conversion but they sure helped. Another thing that helped was being able to look in all the user's private code to discover new ideas that might not be documented elsewhere. Unfortunately this is very difficult in extended professional communities -- if people don't want to share their toys you have to find some other way to learn to play. And you're hobbled with copyright restrictions, licensing, etc. to where it can become expedient to start your own language. So I certianly agree with the crowd that has little or no sympathy for Andy's position that providing decent method comments is "too expensive" as Chris put it. And I don't need to see 10 different flavors of documentation, spread over tutorials, classes, methods, manuals, help, and so on. I would like to see it all in one easy to access place. And as an example to users to encourage them to write thiers, I believe the best place for this documentation is right in the code or the method comments. If users have to go through a slow approval process to get their comments into the next version's helpfile or tutorial, that's too slow. The community should be able to share comments here on the newsgroup just as they can share code and other help. |
In reply to this post by Kirk W. Fraser
Dolphineers,
While I wouldn't mind having more and better class comments to read, getting them seems to be just a question of putting in a little more work to write them. My priority instead would be to add a mechanism to document class and instance variables in a way that could be easily maintained and updated, which would be more of a design and standards problem. Describing variables in the class comment is not such a way. In many languages, one can do this (forgive the poor example): int bufferIndex; // Formerly known as i static int bufferSize; // Limit this to 16K according to RTF specification static char *buffer; // Pointer to char array of size bufferSize In Smalltalk you could do the following, but of course the comments are forgotten except for a record in the change log. MyObject subclass: #Object instanceVariableNames: 'bufferIndex' "Formerly known as i." classVariableNames: 'BufferSize' , "Limit this to 16K according to RTF specification." 'Buffer' "Pointer to char array of size BufferSize." poolDictionaries: '' classInstanceVariableNames: '' If the comments are written to the class comment instead, that information will be obsolete if ever the variable names change or some get deleted or added, etc. Instead, why not make a method that takes not a space separated list of variables but an ordered collection of associations between a variable name and a comment? This method can collect the variable names into a string and forward it to the normal #subclass:instanceVariableNames:... method. It also keeps the variable comments around for later use. For example, in the class browser it shows the comments underneath the class definition in comment like this: MyObject subclass: #Object instanceVariableNames: 'bufferIndex' classVariableNames: 'BufferSize Buffer' poolDictionaries: '' classInstanceVariableNames: '' " bufferIndex - Formerly known as i. BufferSize - Limit this to 16K according to RTF specification. Buffer - Pointer to char array of size BufferSize. " A dialog was recently added to Dolphin for adding a class. An additional dialog could be used for editing a class. (Editing the strings which have to be re-parsed for every change is primitive, isn't it?) It could support the reordering, insertion, and deletion of variables, displaying the variables in the parent class, listing potential pool dictionaries, and, of course, displaying and editing the variable comments. Anytime a variable was changed, the comments would change with it. When a variable gets added, the UI would nag you for a comment. Comments, anyone :-) Keith Kirk W. Fraser wrote: > > Andy, > > Here's a first sample -- I figure we'll either agree or agree to disagree > before putting too much effort in. I wrote this to replace the class > comment for Array. It could also be used in "About" methods, help, > tutorials, and so on. IMHO it's way more helpful than the existing class > comment. Further improvements welcome. > > 'Array is the simplest data structure beyond a single variable. > Imagine a row of numbered jars. > You can put any object in any jar using at: aJarNumber put: anObject. > You can view the contents using at: aJarNumber which must be an integer. > > Arrays have the limitation of being fixed length. > You can define virtually any length with Array new: size. > > More complex data structures use Arrays to hold their variables and grow by > copying to a bigger Array or organizing groups of Arrays. > > Arrays can be used in loops. > array do: [:jar | "action on individual jar contents"). > > For more information on Arrays be sure to see the Help reference and > tutorial information.' > > Kirk |
Hello all,
I'm less worried about documenting instance variables for a few of reasons: (1) they can have different meanings at different times; (2) they are typically hidden state that shouldn't be of much interest unless one is really paying attention to or modifying the details of the methods (so good comments therein should be more helpful); (3) I'd rather see an author of a class write a comment about how/when/why I would use the class. FWIW, I'm finding that a good package comment is typically of the most use to me in (re)understanding my own frameworks. That's in part because it's the first thing I see when I invoke my package documentation system, and because classes often work together, so the package/framework level is a good place to write how-to documentation. Have a good one, Bill -- Wilhelm K. Schwab, Ph.D. [hidden email] |
In reply to this post by Keith Alcock-3
[for some reason OE is playing up trying to post this. Apologies if you see it
several times. Or not at all ;-) ] Keith, > It surprises me greatly how C programmers (including me up until I learned Smalltalk) > are willing to use "unwrapped" functions and constants like this. I don't want to come across as defensive (after all, why would I want to defend a poxy, jumped-up, young C programmer ? ;-) but the code *was* part of my wrapper layer... -- chris |
In reply to this post by Mark Roberts
[hidden email] (M. Roberts) writes:
> For example, consider the books offered by a publisher like O'Reilly & > > Associates, and look at the titles for PHP and Python. What would it > take to get a similar title published for Smalltalk? An example of good documention is the Python library documentation. It is just a set of HTML files, but it describes all the packages that is included with Python, gives a short description of all classes and methods, and some small trivial examples on how to use them. I think that Dolphin users could benefit from this, as I know that the documentation helped and helps me a great deal when I am programming Python. Anyone interested in viewing the python documentation can go to www.python.org -- Vennlig hilsen Syver Enstad |
In reply to this post by Chris Uppal-3
You are too honest ;>
"Chris Uppal" <[hidden email]> wrote in message news:3dda5994$0$114$[hidden email]... > [for some reason OE is playing up trying to post this. Apologies if you see it > several times. Or not at all ;-) ] > > Keith, > > > It surprises me greatly how C programmers (including me up until I learned > Smalltalk) > > are willing to use "unwrapped" functions and constants like this. > > I don't want to come across as defensive (after all, why would I want to defend > a poxy, jumped-up, young C programmer ? ;-) but the code *was* part of my > wrapper layer... > > -- chris > > |
In reply to this post by Kirk W. Fraser
Andy & Blair,
The discussion on documentation has hushed and to me the biggest observation is so few were interested in the topic when I also posted an invitation on the other newsgroup. So maybe there is not much market for documentation. The lessons collected from everyone include: >From C.L.S. Patterns thread: A) Design documentation is only needed if users are expected to modify code. B) There is no excuse for not having good application user documentation. Example: Provide documentation on how to use D.5 ActiveX code to link to services, not on how the code was designed. C) Patterns may help improve code beauty, elegance, and style but do not solve problems. >From C.L.S.D. Documentation thread: A) Documentation consumes time whether done by vendor or in the heads of users and dispensed through the newsgroup instead of the product. B) Both preschool and developer level documentation can be integrated in class comments. C) The Wiki is unreliable (loses information) so its users have abandon it. D) Types of desireable class documentation being aware to make it useful, not just a boring checklist that results in useless information: 1) A practical statement about why the class exists. (This statement should not require update work for new releases). 2) How to immediately use the class stand-alone in interesting ways. 3) How the class is used in combination with other classes. 4) Usage assumptions - what must be true to make it work. E) Full documentation can include class and method comments, user's guides, tutorials, API descriptions, reference guides, tools reference, on-line help, etc. F) A more complete Dolphin book could be written -- see PHP & Python books. G) HTML is a good alternative documentaton delivery system. H) Tutorial and developer comments can be seperated (EXCEPT tutorials show only one way of doing things instead of an explaining all ways including the one you happen to need). I) Perhaps the reason for dismissing method comments is for lack of having seen some good ones that were actually helpful i.e. a self-fulfilling prophecy. J) Making sure documentation and code agree sometimes saves the code! K) People have claimed languages were self-documenting since the days of COBOL and it only true in trivial examples which people already understand. L) Test driven programming doesn't naturally fit with documenting but that implies incomplete analysis - schools teach adequate analysis before coding takes no more time and can produce better results. Analysis is compatible with having enough documentation you don't have to read the code. (It may be the difference between programming and hacking). M) It is interesting the D.5 line is named XP and provides a refactoring browser yet little or nothing of Kent Beck's methodology is either explained or footnoted with a book citation. Is this an example of going extreme at not documenting? N) It's better to error on the side of too many comments than too few. O) It could aid the existance of class documentation to cause the browser pop-up to provide space for it (require a non-blank entry) when creating classes. P) Whether provided at the package, class, or method level, a clear statement on how/when/why to use a piece of code is a good thing. Thanks to all for your input to this discussion. If your remarks aren't adequately summarized here, tell me. There are a lot of good ideas. I was also surprized no one provided other examples to help document everyone's image. Further analysis of these ideas I think could lead to a reasonable standard for Andy and Blair which would not be too costly for them to generate or maintain. In the interest of proposing a low-cost documentation system for them, here is another analysis pass: --------Low Impact Documentation---------- Andy and Blair are requested to give a wee bit more attention to documentation. To make it as wee as practical, please add an editor to the class creation pop-up window that feeds the class comment holder, requiring non-blank entries to: 1) Why is class needed? 2) When would it be used? 3) How can it be used? This simple editing feature should be integrated with the refactoring browser to save comment integrity over class name changes. This update should exist in Andy & Blair's development image even if the tool is not sent out in a release update for others. It of course can be defeated but I hope it gets the idea across and would serve as a reminder. Sincerely, Kirk W. Fraser |
Free forum by Nabble | Edit this page |