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? >
I try to write full Javadoc for public methods because it is expected of me. I try to include why the class or method exists and where it is used. But with proper naming I can make the comments less necessary. AccountDao.updateBalance(Account account, Money newBalance) is better than Database.update(Account a, Money m), and much better than names like doProcess(), or save(), or xyzzy(). But Java and some external libraries do provide some help that many programmers ignore. The annotations in javax.validation are useful, even if one does not use the Hibernate or Apache implementations. Person.setSurName(@NotNull @Size(max=40) final String newSurname) tells the reader important information at a glance. Without additional support, the annotations are just hints to the user, but they save sentences in documentation. Sadly, there is no endorsed weights and measures library. I'm not sure what happened to that JSR. But there is a nonsubtle difference between public Area surfaceArea(final Length length, final Length width, final Length height) and the equivalent with double parameters and return type. I've seen situations where the parameters came from different sources and were not normalized to the same unit of measure. We don't want our programs to crash into Mars. At least we all have TimeUnit.convert. respectfully, Eric Jablow -- 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/-/DTxV4aogZR8J. 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.
