Interesting... That summary makes me revisit my own opinion :) I've now court it down to this: Document INTENT, don't document details that can (and should) be intuitive from reading the source code. On Aug 17, 2012 7:23 PM, "Vineet Sinha" <[email protected]> wrote:
> 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. > -- 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.
