If I want a bird's eye overview of what a thing does and very VERY roughly how the API is structured, I'll look at a tutorial or an example. If I have to resort to scanning the javadoc that's already a big minus for this library.
If on the other hand I'm already using it and I'm just trying to figure out exactly how to do some tricky thing or trying to get a refresher on how to do X, eh, I'll take code please. Javadoc is nice too, it doesn't matter that much. But I at the very minimum want code. That way, if something is wrong I can quickly check if I have misinterpreted what I thought the library is doing, and I can debug through it much more easily. Therefore, if I was given a choice: Code or javadoc? Code. Every time. On Tuesday, August 21, 2012 8:44:40 PM UTC+2, Jeb wrote: > > >>"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. > > That seems like a pretty bold claim to make in general. javadoc can be > pretty useful for getting a bird's eye view of the big api, then zooming in > to what you need. That's nice for a variety of reasons, such as comparing > two similar libraries. > -- 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/-/16wkU2jpA1QJ. 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.
