begin quoting Gabriel Sechan as of Tue, Dec 12, 2006 at 11:54:52PM -0600: > >From: Christopher Smith <[EMAIL PROTECTED]> > >> > >Yeah, Smalltalk folks in general tend to frown on comments. They see it as > >a sign that a method is complex.
I generally think that the reason comments aren't well-liked by Smalltalkers is that the comments are awkward. They aren't prefixed by an unnatural character sequence, they're just stuff in double-quotes. Consequently, comments in Smalltalk are awkward. Pascal, with (* and *), or C with /* and */, or C++ with //, shell-scripts with #, and so forth and so on, are easier to write comments in. > > Complexity is sometimes warranted (in > >which case comments are insisted upon, rather than frowned upon), but most > >often not. The preferred approach is to have short methods with > >descriptive names (this is helped tremendously by the way Smalltalk method > >names work when you have multiple parameters). > > Meaningful names are good, but nowhere near sufficient. Agreement! > They don't tell us > what assumtions have been made, valid input ranges (if not the entire range > of the type), or why you're doing what you're doing (general rule of > comments- why, not how, unless the how is really complex). The two aren't > exclusive, they complement each other. Yup. Comments are for intent, assumptions, and warnings. > >Don't forget documentation. People think that XP says not to do > >documentation, but it doesn't. It says to push off writing any > >documentation until it's going to be used or the end of the project, > >whichever comes first. The idea behind this is that the projects, the > >code, etc. change over time and you end up with all this "documentation" > >which is inaccurate the first time it is actually used (raise your hand if > >you've not experienced this phenomenon before ;-) or worse still you spend > >all this time refactoring documentation to keep it up to date. > > > There's a multitude of problems with this > > 1)No manager in the world is going to let you sit around documeenting for a > month instead of doing "real work". But they don't have a problem, it seems, with hiring a consultant to sit around for a month to generate a three-hundred-page "design document"... > 2)People leave- they won't be around to document at the end In theory, everyone knows the code and the overall design, since everyone will have worked on just about every part of the program. (In practice, this isn't so. Some folks gravitate towards the UI, others towards the algorithms, others towards the back-end, etc.) > 3)People get added- there's no documentation to bring them up to speed This counts as "actually used". That's actually covered. > 4)XP projects are about rapid iterations- they never really end, so you'd > never get around to documenting That's why you need a coach. "We've done five iterations, this next iteration will be for commenting, updating the documents, and identifying the code that smells." > 5)People forget- half the reason for docs is to remind the programmers of > the design and implementation they're writing. No docs, nothing to go back > to when you're forgetting details Yup! I swear at programmers who don't document, or who document poorly. Generally, this means I cuss myself out a lot -- "why was I satisfied with a two-sentence description of this class?" -- if you gave me a time machine, I might have to go back in time to beat myself up. > Not to mention the pure inanity of it- you're supposed to rapidly refactor > code, but for documentation its suddenly bad? Because code is fast to change and can be regression tested. There's no refactoring tools or unit tests for documentation. Without the tools and computers fast enough to make 'em effective, even XP adherents wouldn't recommend XP. I wonder if anyone has mixed literate programming with XP. That would be... interesting. > Yeah, you need to go back > and tweak it every so often. No big deal. At least you have it to go back > to. Flowcharts are a PITA to revise. A ten-minute change with a thirty-minute test can take an hour or so to update the flowcharts and other diagrams, the design document, the developer manual, the quickstart, and the user manual. > THe idea of no design (or "the tests are the design", which is the > same thing), no documentation, no comments are all signs of a lack of > professionalism, Generally agree, but you're also mischaracterizing XP unfairly. It's just that the documentation isn't in huge MSWord documents with seventeen standard fonts, twelve pages of tracking tables, an acronym glossary, a cover sheet, a title page, a table of contents, a figure list, poor grammar, worse spelling, and passive voice. A complete absence of comments I deplore, and useless comments aren't much better. When comments are required by fiat and process, what is generally the result is that the code is filled with useless comments, of the "i++; // incr var i" sort. I suspect that a programmer who naturally (presumably after being burned many times) writes good comments will continue to do so even if in an XP shop. In fact, when there's someone looking over my shoulder, I spend _more_ effort writing good comments. I get embarassed easily. > a lack understanding of software engineering and quality, > and a lack of respect for your coworkers and those who will maintain the > software. If I had someone on my team who took any of those stances, I'd > do my damndest to get him fired, he's a liability to the team. And it's likely you'd be booted from an XP team with prejudice as well. Not all methodologies are for everyone, after all. One-size-fits-all is a pernicious meme. -- _ |\_ \| -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
