I agree with most of the points above. I have spent a lot of time thinking about this topic and seeing what works in practice.
Self documenting code works in great at explaining WHAT is happening. However, without comments it is very hard to convey the WHY the code is doing what it is doing, the HOW it works, and the HOW to use the component. In my opinion, what I have found in JavaDoc is often useless because it is not in service to the above. I have also personally not found tests to be good documentation (even though some of the people that I respect do use it in that manner). I do believe that my lack of finding success with tests is more a reflection of the attitude around the development teams that I have worked who have not been doing TDD. Beyond code comments, I do recommend three kinds of documents: 1. The mile high view (as many people have mentioned). 2. The heart beat - documenting how the core 'classes' talk to one another. 3. The main use cases - a walkthrough of one or two features from a users experience and how that his the different cross sections of the code. -Vineet On Fri, Aug 17, 2012 at 5:55 AM, Brian Smith <[email protected]> wrote: > I agree they're not mutually exclusive. Encouraging code clear enough to > not require comments is a good thing but it has to actually happen not just > get used as an excuse. > > We have a handful of rules: > > - absolutely no boilerplate or generated comments/javadoc > - code intended as a public API gets full javadoc with example uses > (though again we exclude boilerplatey stuff like accessor methods) > - comments in implementations are only used where: > a) you're doing something unusual and the reasons wouldn't clear to a > maintainer > b) there is a non obvious risk in changing a particular piece of code > > Following these rules, code with almost no comments isn't uncommon or > necessarily a problem. We pair rather than do formal review which we find > works quite well, people tend to find it easier to keep a discipline when > not working solo. > > The essential thing IMO is to put yourself in the position of having to > maintain it a couple of years from now, you don't want clutter or comments > that have become inaccurate over time, but you do want the necessary > information. It's a balance to find. > > > On 17 August 2012 10:37, Carl Jokl <[email protected]> wrote: > >> I just feel writing self documenting code is not mutually exclusive to >> writing documentation and comments. My thinking is making the code itself >> clear means less need to stick lots of comments in it to explain what is >> going on. I didn't see this as meaning no comments were needed at all just >> that less need to be written. As regards classes and methods, those >> comments cover what a class or method is intended to do and not the >> implementation details of how it does it (unless it is really necessary or >> well understood e.g. LinkedList vs ArrayList). >> >> -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/javaposse?hl=en. > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.
