tag:blogger.com,1999:blog-6479932290949673745.post4119374372625769307..comments2022-12-21T05:15:25.565-05:00Comments on Geek in a Suit: Testability - re-discovering what we learned and forgot about software
development.Anonymoushttp://www.blogger.com/profile/11149956661907218421noreply@blogger.comBlogger3125tag:blogger.com,1999:blog-6479932290949673745.post-61806726452023497222009-01-14T12:22:00.000-05:002009-01-14T12:22:00.000-05:00I wonder if I agree about the documentation commen...I wonder if I agree about the documentation comment. It's not that I disagree with the underlying principle - "communicate your intent." However, I find that often the documentation is overly verbose and actually leads to difficulty in understanding. I like to balance things by making my code relatively granular and component-oriented, with explicit dependencies between components where the very names of the dependency make the collaboration obvious. <BR/><BR/>This has the advantage of making a lot of interactions and collaborations auto-generatable from the code (using reporting tools such as maven's site reports), because the intent is clear in the very structure and naming.<BR/><BR/>However, having said that, I usually also include a lot of usage examples, key entry-points, and any non-obvious interactions in documentation. But for the latter I often find that if I have to document it extensively, then I haven't broken it into the right sized pieces. It's not dogmatic, but I find that's typically the case.<BR/><BR/>So yes, document, and in plain English with code samples, but also make sure that as much as possible, the very structure and style of naming self-documents so you require less duplication of information. That way you can avoid the risk of stale documentation.Anonymoushttps://www.blogger.com/profile/11149956661907218421noreply@blogger.comtag:blogger.com,1999:blog-6479932290949673745.post-83452295097360695182009-01-14T03:40:00.000-05:002009-01-14T03:40:00.000-05:00Great article! I, too, have noticed some sort of O...Great article! I, too, have noticed some sort of OO renaissance in the past few months.<BR/><BR/>In the recipes section, you left out someone who I consider to be the most convinced and fervent proponent of good OO design: H. S. Lahman.<BR/><BR/>For those interested, his blog-ish site is at http://pathfinderpeople.blogs.com/<BR/><BR/>Eddy.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-6479932290949673745.post-6747158773603145022009-01-14T01:18:00.000-05:002009-01-14T01:18:00.000-05:00Documentation. Documentation. Documentation. Docum...Documentation. Documentation. Documentation. Documentation. Whatever you do: documentation. It is true very few will read it, but those that do REALLY REALLY REALLY need it.<BR/><BR/>Document everything: your patterns, why you chose them, how to use them, how to scale them. Document what each class/object does. Document all bit twiddling. Make constants and document them: magic numbers are evil. Document interfaces between various components, especially hardware components.<BR/><BR/>The difference between a feature and a bug is intent. If you don't know the intent, how can you know if it is a feature or a bug? <BR/><BR/>Testing doesn't always help, as the test itself could be buggy or ambiguous. Or inaccessible. Write it down. In. Plain. Language.RowliRowlhttps://www.blogger.com/profile/05814340557765245023noreply@blogger.com