The distinction between API documentation and inline comments is an important one - the two have almost nothing to do with each other. I'll assume that we're all on the same page about what constitutes good API documentation: I want to know what the arguments are and in what ways they're restricted, I want to know what exceptions are thrown and under what circumstances, and I want to know enough about the implementation to judge whether this is a good fit for my purposes. (for example, if you're taking a list and repeatedly accessing elements by index, I want to know about it, so I don't give you a linked list) That being said, I find myself standing in a middle ground on the issue of inline comments. I see no contradiction between striving for code that needs no comments at all, because it is perfectly clear from start to finish, and also insisting that comments should be included when they are actually needed. So to me, this is largely a non-issue: I know when comments are needed because I am irritated by the lack of them, and I know when they are not needed because I am irritated by their presence. If I am not irritated, the comments are correct.
On Mon, Apr 15, 2013 at 1:00 PM, Josh Berry <[email protected]> wrote: > At face value, I do not see why programming should be any more unique than > any other process description out there. I like to bring actual cookbooks > and furniture assembly examples into play. Cookbooks are typically more > prose heavy then furniture descriptions. Even there, though, it is not > uncommon to see callouts that are essentially comments. > > > On Mon, Apr 15, 2013 at 7:26 AM, Alexey <[email protected]> wrote: > >> It seems that a big thing that should always be discussed as part of this >> topic is what the nature of the comments is. Javadoc was brought up and I >> dare say that kind of information is absolutely necessary and is not on par >> with inline comments that one only sees when looking at the source code. >> API comments are directed almost squarely at the consumer of said API and >> themselves can be broken up into 2 categories: >> >> 1. necessary information otherwise not captured by the programming >> language (so many of API comments I see in Python these days start by >> saying something about input and output types and so many comments in >> general talk about possible exceptions otherwise not seen by explicit >> checked exception declarations) >> 2. some helpful information about general intent and intended use of >> the API -- could be considered technically superfluous, but sometimes oh >> so >> necessary to the human trapped inside of us struggling to get out :) >> >> Personally, I think there's a time and place for both. It's not possible >> to capture every good piece of information that's necessary at the time of >> authorship of the code or in some perceivable future in strict language >> artifacts alone. I see and write plenty of code completely devoid of >> comments. That sort of thing is usually obvious in its intent in the >> context of the project. But not everything is obvious and therefore >> there's no shame in giving future self or your colleagues or >> co-conspirators a helping hand. >> On Sunday, April 14, 2013 2:44:58 PM UTC-4, Reinier Zwitserloot wrote: >> >>> On the discussion on whether comments are good or bad, I posit: >>> >>> Code which is eminently understandable based solely on the name of the >>> method, the code, and the names of variables and parameters is always >>> better than code which requires comments to be easily understood, and also >>> better than code which is just as understandable but which has comments in >>> it (those comments are therefore superfluous). The reason comments are, in >>> a vacuum, 'bad', is that they clutter up code and are impervious to unit >>> testing. In practice, they are also notorious for ending up out of date >>> because those familiar with the code are more likely to work on it, and are >>> also more likely to mentally screen out the comment and thus not realize >>> when it becomes out of date (and thus, misleading, very bad). >>> >>> Of course, let's be reasonable here: While in theory any and all >>> comments are code smells, they are pretty much always the lesser evil. >>> Anything beyond the most academic of projects is going to have some chunk >>> of code which does something in a somewhat weird way for a good but not >>> immediately obvious reason, and the right choice is definitely to add a >>> comment to explain what's happening. >>> >>> However, for a great many comments, it could have been solved with >>> helper methods. We should all aim to do that more. Helper methods make it >>> easier to test code and are more effective at helping people new to this >>> code understand it all than comments. >>> >>> The notion that comments are the lesser evil is even more true for APIs >>> (so, javadoc). The best theoretical API is fully understandable based only >>> on a quick tutorial video and the names of types, methods, and parameters. >>> In practice, there are caveats and other details that you shouldn't bother >>> putting into the tutorial or the names, but do warrant mention. Again, >>> lesser evil: It would be even better if the API was such a fantastic >>> mapping onto the problem domain that there aren't any caveats in the first >>> place, but in practice life just isn't that nice of course. >>> >>> >>> >>> I believe treating comments as 'bad, but not a big deal' leads to the >>> right decision in general. Comment where neccessary, put in reasonable (but >>> don't go entirely out of your way) effort to avoid writing them by cleaning >>> up code to alleviate the need for them, and at all costs don't comment just >>> for the sake of adding comments. >>> >>> -- >> You received this message because you are subscribed to the Google Groups >> "Java Posse" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected]. >> To post to this group, send email to [email protected]. >> Visit this group at http://groups.google.com/group/javaposse?hl=en. >> For more options, visit https://groups.google.com/groups/opt_out. >> >> >> > > -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at http://groups.google.com/group/javaposse?hl=en. > For more options, visit https://groups.google.com/groups/opt_out. > > > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/javaposse?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
