tag:blogger.com,1999:blog-5446881656659329441.post8975232515679531300..comments2015-02-27T15:26:39.812+01:00Comments on Agile Object Design: Comments considered harmfulEivind Nordbyhttp://www.blogger.com/profile/00950648343205866327noreply@blogger.comBlogger2125tag:blogger.com,1999:blog-5446881656659329441.post-20336268576955329802011-11-03T12:15:19.087+01:002011-11-03T12:15:19.087+01:00Yes, Negröj, I also find exceptions. But I like to...Yes, Negröj, I also find exceptions. But I like to think of them as just exceptions. I have been able to get rid of a lot of comments and make code simpler, clearer and easier to read following the main rule.<br /><br />Most of the time, I think that tricky algorithms like ASN.1 do <i>not</i> belong to the exceptions, though. They are just a bit more challenging. I find the solution to be abstraction and implementation hiding. There exists an overall logic, (e.g. for each value, parse the value). Write that (the <i>what</i>s) at a high level of abstraction, and hide the implementation details (the <i>how</i>s). Repeat recursively. Blend in an ounce of polymorphism. At the lowest level, there may be some bit fiddling, but that will be in a small, isolated and easy to understand method with a meaningful name.<br /><br />It might be an interesting challenge to write an expressive, readable ASN.1 implementation without comments. I am sure they already exist.<br /><br />As for optimizations, that is a question of its own. If you have to to down that dangerous route (mind the <a href="http://c2.com/cgi/wiki?RulesOfOptimization" rel="nofollow">three rules of optimization</a>), they will be small, isolated islands requiring high attention. Optimization in itself introduces redundancies and complexities. Don't be surprised if you have to break some more guidelines as well along the road.Eivind Nordbyhttps://www.blogger.com/profile/00950648343205866327noreply@blogger.comtag:blogger.com,1999:blog-5446881656659329441.post-44467696199090694802011-11-03T11:30:46.409+01:002011-11-03T11:30:46.409+01:00I think there are two types of comment. One descri...I think there are two types of comment. One describes interfaces for external consumption (i.e. APIs). These should in most cases be self documenting. It's a different story if you are selling the API in binary form... Of course, you could document the API in a parallel Word document, but that's documentation one more step removed from the code, increasing the risk of inconsistencies.<br /><br />The other describes "rough patches" in the code. By rough patches I mean code that does something complicated. For instance bit twiddling for ASN.1. You could of course put a reference to the standards document in a comment at the top of the source file, and be done with it. But I think you owe it to the maintainer of the code, to describe what the code is doing. I often find myself drawing cute ASCII pictures on how the bytes and bits are laid out in memory. Also, if you're doing some super duper optimization that isn't obvious at the first glance, I think it's a good idea to put a comment that outlines the optimization method.<br /><br />It's a tricky balancing act...Negröj Nossdravgishttps://www.blogger.com/profile/08495229365918135333noreply@blogger.com