For what it's worth, Google mandates a very strong culture of comments in their code base. Your commit will simply be rejected by the reviewer if it's not commented properly, and since you know that, you save yourself the trouble and you put the comments in before submitting.
I don't remember any guideline about what these comments should be, how they should be worded and what they are supposed to document. I guess that after a while, you just learn what a good comment is. Take a look at the Guice or Guava Javadocs if you want to get an idea, but the bottom line is that these comments are extremely useful and they are in no way redundant with the code, no matter how clear that code is. Anyone who tells you that comments are made unnecessary by good code has probably never worked on anything else than solo or toy projects. Another argument in favor of comments is that they are a great way to familiarize yourself with a huge code base in much less time than it would take you if you had to read the code. A good three line comment allows you to understand twenty lines of code without having to read that code, which is critical when you are trying to get up to speed fast. -- Cédric On Sat, Aug 18, 2012 at 5:15 AM, Kevin Wright <[email protected]>wrote: > I've seen this tactic before, and it *does* work. > > If you can't comment trashy code to explain it, then you find yourself > refactoring more to make it explain itself. The policy is most effective > when used in an environment that practices code reviews and/or pair > programming. > On Aug 18, 2012 1:05 PM, "mgkimsal" <[email protected]> wrote: > >> Making an assumption here that your shop is 'agile'. I've worked in >> projects where 'agile' was primarily an excuse for management to avoid >> letting anyone do any upfront planning whatsoever - "hey, just be agile!". >> Your situation seems to be a similar abuse of the concept of "readable >> code". Yes, your code should be readable, but not necessarily to the >> exclusion of clarifying comments. >> >> My other assumption here is that you have few tests. Having tests as >> 'executable documentation' is a good suggestion, but if they can't keep >> *comments* up to date, I'm doubtful there's efforts made to keep a test >> suite up to date. >> >> The justification is "it would just be painful overhead to keep JavaDoc >> comments up to date." However, it's a known overhead. While it certainly >> does add time to the project, that's part of the cycle of software >> development - a known/fixed cost. What you have now is a situation where >> new people coming in to code are *much* more likely to take an unknown (and >> likely high) amount of time - I'd wager more time will be spent on new >> people understanding the complexity of the code than it would have taken to >> keep it up to date over the project lifetime. Even if it wasn't *more* >> time, it still is burdening new developers with more complexity an unknowns >> than they should be expected to deal with, which may also introduce bugs >> which would have avoided with proper documentation. >> >> In short, this attitude is extreme short term thinking, focused on the >> needs/whims of a few personalities, vs what will serve the business' needs >> over the lifetime of the project. >> >> >> On Friday, August 17, 2012 5:18:26 AM UTC-4, Carl Jokl wrote: >>> >>> I had a discussion very recently within my company regarding the source >>> code produced and that it has almost no comments in it. I was told quite >>> confidently by the developer I spoke to that this was a deliberate company >>> decision and that the code should be clear enough that no comments >>> were necessary. Also it was said that the code and methods were changing so >>> often that it would just be painful overhead to keep JavaDoc comments up to >>> date. >>> >>> I understand the principle of trying to make code self documenting and >>> clear enough so that it does not need lots of documentation. I am not sure >>> however how I feel about the idea of using this argument not to add much of >>> any comments at all. Am I just not with the times or Agile enough? >>> >>> What are your thoughts? >>> >> -- >> You received this message because you are subscribed to the Google Groups >> "Java Posse" group. >> To view this discussion on the web visit >> https://groups.google.com/d/msg/javaposse/-/DBxX-1OArV4J. >> 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.
