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.
