Not particularly a reply to Reinier.. I aim to make my code self-explanatory. The 'why' is in the commit messages and the tickets they link to. If I can't make the code self-explanatory I will add an explanation. Anything that looks like it might be an accident but isn't, I will add an explanation, e.g., a fall-through in a switch.
If I need to Javadoc an API, that's fine but I'll try to resist until the area has stayed unchanged for a while because I don't like out of date Javadoc. I'd rather spend the effort on writing a tutorial with code samples that get compiled so stay up to date. "And wait for when you got away from it for six months. Let's see if you can still read it undocumented. :-)" Yes, I can in general read my own code years later without comments. I can also read others' code without comments in most non-pathological cases. My biggest barrier to understanding code is closed-source libraries like Crystal Reports, WebSphere.. "And as a user of an api, would you rather read the code or the javadoc ? " The code, in general. It's more likely to be correct. If the code looks bad then the javadoc *might* clarify the intent but commit messages are more likely to be accurate assuming you don't have a 'Latest changes' guy on the team. "- I much prefer test cases to Javadoc. Call it 'executable' documentation if it makes you feel better :)" I like this idea but I regularly stumble across test cases where it's hard to tell whether the items being tested give certain values because that's the intent or because someone fiddled with them based on an implementation until the test passed. That makes me cynical, hopefully better test cases will prove self-documenting. On Mon, Aug 20, 2012 at 10:27 PM, Reinier Zwitserloot <[email protected]>wrote: > Yes, comments are bad. Of course, leaving a piece of very confusing code > uncommented is worse, in which case you pick the lesser evil of commenting > your tricky hack. But, if you can refactor your hack into code that is so > easy that it warrants no comments, that's best of all. > > Javadoc, of course, aren't comments at all. These are API documentation. > For places where API documentation is out of place (which aren't very many > places; a proper project has lots of modules, internal or no, and that > means somebody, possibly even yourself in another source file, is a user of > your 'API' so to speak), lack of javadoc is obviously fine. There's also > very little point in documenting a method with the obvious, i.e. > documenting a setName method in a Person class with 'sets the name of the > person', especially if you then also throw some @param etc tags on there. > Utter waste of time and a complete pain if you ever want to refactor this > code. > > So, the gist is right. I can't tell if they are going overboard with this > sentiment without looking at the code, though. > > > On Friday, August 17, 2012 11:18:26 AM UTC+2, 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/-/i2z1vWqk8aEJ. > > 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.
